Skip to main content


Requests to the Atomic API are authenticated using the client credentials oauth2 flow, via a client id and secret created in the Atomic Workbench. The basic flow is:

  1. Base64-encode your client id and secret i.e. echo -n "$CLIENT_ID:$CLIENT_SECRET" | base64
  2. Pass this value as the Authorization header in a request to our oauth server
  3. Use the returned token to authenticate requests to Atomic

Atomic's oauth url is:

Tokens have a limited lifespan, so should be renewed when appropriate.

Note: requests to the Atomic API must include a User-Agent header.

Caching API tokens

When accessing the Atomic API programmatically, each API request should not request a new token. Instead, tokens should be cached and used until expiry and then a new token requested. The oauth endpoint used to retrieve tokens is rate limited and will return HTTP 429 status codes when used at too high a rate.

Full authentication example

Requires bash, and the shell utilities curl, base64, and jq.

Values for org_id, client_id and client_secret can all be managed in the Configuration section of the Workbench. Read more about this in the API section of the Workbench guide.



# fill in your organization id
ORG_ID=<your org id>
# fill in your API credentials for the environment you want to send requests to
CLIENT_ID=<your client id>
CLIENT_SECRET=<your secret>


# base64 encode your credentials

# retrieve access token details as json
TOKEN_DETAILS=$(curl -X POST "$OAUTH_URL?grant_type=client_credentials&client_id=$CLIENT_ID" \
--header "Content-Type:application/x-www-form-urlencoded" \
--header "Authorization: Basic $CREDENTIALS")

# parse the token value
TOKEN=$(echo $TOKEN_DETAILS | jq -r -c ".access_token")

# retrieve Environment details
ENVIRONMENTS=$(curl -X GET "$ATOMIC_API/v1/environments" \
--header "Content-Type:application/json" \
--header "Authorization: Bearer $TOKEN")

# store first Environment id for use in other examples
ENVIRONMENT_ID=$(echo $ENVIRONMENTS | jq -r ".environments[0].id")

# output environment details, formatted with jq

The output should be a list of Atomic environments you have access to, similar to

"id": 123,
"name": "production",
"created": "2019-07-04T04:18:08.153Z",
"organisationName": "Your organisation"

API credential roles

Each API credential pair is scoped to the environment and assigned one of the following roles:

  • auth - used only to create and rotate other credentials
  • workbench - used to manage workbench resources such as cards and SNS platforms
  • events - used to create cards, and manage customers

The Atomic API spec shows for each request which role should be used.

For example, GET cards requires an events token:

summary: "Retrieve cards (token: events)"

If you haven't added any API credentials yet, follow the steps as described in the Authentication controls section to add new ones.