Environments API

The Environments API returns the Atomic environments your authenticated credentials can access. It is typically the first call you make after authenticating: every other endpoint in the Atomic API is scoped to an environmentId, and this endpoint is how you discover the ids that are valid for your token.

The API supports:

• list environments the current token can access

Authentication

The Environments API is available to any authenticated token, regardless of role or scope. Both legacy API keys (with the auth, workbench, or events role) and fine-grained API keys can call it - the response is filtered to only the environments the underlying credential pair has access to.

You can interact with the Environments API using Insomnia (follow the Insomnia instructions) or curl. When using curl, you'll need to set up your Authentication first.

Detailed specs and examples can be found in the Atomic API spec for the Environments endpoint.

API endpoints

List environments

Returns every environment the current token can access. There are no path or query parameters - the response is determined entirely by the credentials presented on the request.

curl -X GET "$ATOMIC_API/v1/environments" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $TOKEN" | jq

Sample response

{
  "environments": [
    {
      "id": "4dkLrv",
      "name": "production",
      "created": "2020-01-16T10:00:00.000Z",
      "organisationName": "My Organisation"
    },
    {
      "id": "9pXqAa",
      "name": "staging",
      "created": "2020-01-16T10:05:00.000Z",
      "organisationName": "My Organisation"
    }
  ]
}

Response fields

Each entry in environments has the following shape:

Field	Type	Description
id	string	Environment id. Use this as {environmentId} on every other endpoint that takes one.
name	string	Human-readable environment name as it appears in the Atomic Workbench (for example, production, staging).
created	string	ISO 8601 timestamp for when the environment was created.
organisationName	string	The organisation that owns the environment.

Errors

• 401: No auth token provided, or the token is invalid or expired

More

• Authentication - how to obtain the bearer token used on this endpoint, and an end-to-end example that calls /v1/environments to bootstrap an ENVIRONMENT_ID variable
• API credentials - how to issue fine-grained API keys and what scopes they need for other endpoints