Getting started with the Gremlin API

All requests to the Gremlin REST API require an access token provided in the Authorization Header. There are two ways to retrieve an access token:

1. By authenticating using your Gremlin account credentials and receiving a Bearer token.
2. By using a user or team-level API key.

‍

Authenticating using your Gremlin credentials

Authenticating with a username and password

If you log into Gremlin using a username and password, you can receive a Bearer token by providing your credentials to /users/auth:

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'email=[your email]' \
    --data-urlencode 'password=[your password]' \
    'https://api.gremlin.com/v1/users/auth?getCompanySession=true'

‍

Authenticating with multi-factor authentication (MFA) enabled

If you have MFA enabled, include the token from your password authenticator in your call to /users/auth/mfa/auth:

curl -X POST --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'email=[your email]' \
    --data-urlencode 'password=[your password]' \
    --data-urlencode 'token=[your TOTP token]' \
    'https://api.gremlin.com/v1/users/auth/mfa/auth?getCompanySession=true'

If you’re a member of more than one company, you can specify the company by adding companyName=’[your company name]’.

‍

Receiving the bearer token

If your authentication was successful, Gremlin will return a JSON response containing a bearer token, as well as other information about your session:

{
  "company_id": "07814fbb-a9a0-81e4-b375-980f680a70c4",
  "company_name": "My Company",
  "roles": ["COMPANY_USER"],
  "privileges": ["COMPANY_DEFAULT"],
  "expires_at": "2099-01-00T00:00:00.000Z",
  "header": "Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGM0OmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAy",
  "identifier": "gremlin@gremlin.com",
  "teams": [
    {
      "identifier": "e7352a6b-a9a0-513c-81e4-980f680a70c4",
      "name": "My Team",
      "company_id": "07814fbb-a9a0-81e4-b375-980f680a70c4",
      "roles": ["TEAM_USER"],
      "privileges": ["READ_TEAM_USERS", "TEAM_DEFAULT"]
    }
  ],
  "last_login": "2098-01-00T00:00:00.000Z",
  "renew_token": "5ca1ab1e-dead-beef-ffff-0000ffff0003",
  "token": "5ca1ab1e-dead-beef-ffff-0000ffff0002"
}

‍

Note the ”header”: “Bearer …” key-value pair. You’ll need this value for future API calls.

‍

Formatting API calls using bearer tokens

When running API calls, include your bearer token as a header. For example, this command starts a CPU experiment using the bearer token from Receiving the bearer token:

# Add 1 core of CPU load to a random host for 30 seconds
curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer ZTczNTJhNmItYTlhMC01MTNjLTgxZTQtOTgwZjY4MGE3MGM0OmdyZW1saW5AZ3JlbWxpbmluYy5jb206NWNhMWFiMWUtZGVhZC1iZWVmLWZmZmYtMDAwMGZmZmYwMDAy" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "cpu", "args": ["-c", "1", "--length", "30"] },
        "target": { "type": "Random" }
    }'

‍

Authenticating using API keys

Instead of using your username and password, you can authenticate using API keys. These are tied to your Gremlin user account and have the same privileges as your user. This also lets you create user accounts specifically for running API commands (i.e., “service accounts”).

‍

Creating a new API key

1. Go to your Account Settings and select the API Keys tab.
2. Click the New API Key button.
3. Give your key a unique Name and an optional Description.
4. Click save, and copy your key.

Now, when formatting an API call, use Authorization: Key [api key] in place of Authorization: Bearer [bearer token]:

curl -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Key f02868098b13e4f68da82b0c5e5c950ea750fce53c62d982cdab0c61099e5f98" \
    https://api.gremlin.com/v1/attacks/new?teamId=e7352a6b-a9a0-513c-81e4-980f680a70c4 \
    --data '
    {
        "command": { "type": "cpu", "args": ["-c", "1", "--length", "30"] },
        "target": { "type": "Random" }
    }'

‍

Revoking an API key

‍

1. Go to your Account Settings and select the API Keys tab.
2. Click on the 3 dots to the right of your API Key.
3. Select Revoke Key and confirm by clicking the Revoke button.

If you want to reinstate a revoked API key, click Reinstate Key instead.

‍

API Key limitations

There is a limit of 5 active API keys per user.

‍

Managing API keys on the Company level

For users with the API_KEYS_READ, API_KEYS_WRITE, or ALL_API_KEYS_READ privileges, there is now an API Keys tab located on the Company Settings page. This page lists all user-level API keys that your users have created. You can search by the name of the API Key or the name of who created it. This is to provide insight for if you plan to remove a user or edit their roles, you know what API keys will be affected by the change.