The ChaosSearch API endpoints use Amazon-style request signing methods for authenticating with the ChaosSearch service. Most ChaosSearch REST endpoints use AWS V4 signing, with the exception of the /user endpoints, which require Java web tokens (JWT) created for the primary/tenant ChaosSearch user for authentication. This topic describes these authentication methods, and how to use them.

📘

Amazon-Style Request Signing

For more information about the AWS REST authentication and methods, see:
https://docs.aws.amazon.com/AmazonS3/latest/dev/RESTAuthentication.html. If you have questions, please contact our Customer Success team.

Using Tokens to Authenticate

Permitted users can use the /user/login API to acquire a secure Java web token (JWT) from the ChaosSearch service. This is the same process that occurs when a user logs in to the console interface directly. The token can be used as part of a specific x-amz-security-token header in REST requests when calling the ChaosSearch APIs.

A JWT provides secure authentication for a primary/tenant or subaccount user. The command outputs a token that is valid for 24 hours for the associated user.

Token authentication is a two-step process:

1. Request a token for a ChaosSearch user and password.
2. Use the resulting token for the subsequent endpoints.

To request a token:

1. Make sure that you have the user account, password, and the ChaosSearch external ID.
2. Use the /user/login endpoint to request the token as follows. ParentUid is required for a subaccount user to obtain a token:

curl --request POST \
     --url https://<chaossearch domain>/user/login \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-amz-chaossumo-route-token: login' \
     --data '{  "Username": "<account>",  "Password": "<password>",  \
            "ParentUid": "<external ID>",  "UniqueSession": true}'

{"Token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJTZWNyZXRBY2Nlc3NL...80LthO5-jS4Ke9AWk"}

The token is a very long string, shown abbreviated above. Copy the token and use it for subsequent endpoints.

To use a token:

1. Make sure that you have token for the user account that you want to use for the REST endpoint(s).
2. Copy and supply the token in a endpoint using the x-amz-security-token property as in the following example to list object groups:

curl --request GET \ 
     --url https://<chaossearch domain>/user/groups \
     --header 'accept: application/json' \
     --header 'x-amz-chaossumo-route-token: login' \
     --header 'x-amz-security-token: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJTZWNyZXRBY2Nlc3NL...80LthO5-jS4Ke9AWk'

[{"id":"a57ccee5-8b7a-438d-a643-5fac0db5e0f4","name":"no-spaces-with-objects","permissions":[{"Actions":["*"],"Condition":...

AWS Authentication for the ChaosSearch API

ChaosSearch uses AWS Sig4 authentication to support endpoints for the object groups, views, buckets, and non-/User related endpoints. Make sure that you have a API key and secret value, the domain name, and the AWS region of the ChaosSearch environment.

The structure of a simple curl command follows, showing the --aws-sigv4 usage:

curl 'https://<chaossearch domain>/V1/' \
  --aws-sigv4 "aws:amz:<region>:s3" --user "<Client Key>:<Secret key>" \
-H 'Content-Type: application/json' \

A sample AwsAuth command line structure follows:

awsauth = AWS4Auth("AWS_Access_Key", "AWS_Secret_Access_Key", "us-east-1", 's3')

Accessing your ChaosSearch API Keys

Make sure that you have your access key and secret key for the API credentials. You can display the access key, and if needed generate a new key and secret, from the API Keys Page.