Skip to navigation
Apps and API

API keys

Let your own scripts and tools start and follow sessions
View as Markdown

An API key lets your scripts, such as a CI pipeline, start and follow sessions without signing in. Each key works in one project and one environment, and only does what its scopes allow.

Everyone can see a project’s keys. Only Admins and the Owner can create and revoke them.

Create a key

1

Open API keys

Open the project, choose the Settings tab, then API keys.

2

Start a new key

Choose New API key and pick the Environment, for example Development.

3

Name it

Enter a Name of up to 60 characters, such as CI pipeline.

4

Pick scopes and expiry

Tick only the Scopes the key needs. Then choose an Expiry: Never, 30 days, 60 days or 90 days.

5

Create and copy

Choose Create key, then copy the key into somewhere safe, such as your CI system’s secrets.

New API key dialog with the Environment, Name, Scopes checkboxes and Expiry fields
The New API key dialog

The key is shown only once. If you lose it, revoke it and create a new one.

ScopeWhat the key can do
Session: CreateStart agent sessions.
Session: ReadRead and follow agent sessions.
Session: StopStop, pause and resume agent sessions.
Session: PermissionsRead and answer permission requests.
Session: ConnectOpen and refresh live connections to sessions.
Project: Read metadataRead project and environment configuration.
Audit: Read logs, Audit: Tail streamNothing yet. They’re reserved for audit logs.

Use a key

Send the key in the Authorization header of each request, as Bearer <your key>, to https://us.api.aosplane.io.

Revoke a key

Choose Revoke on the key’s row, then Revoke key. Anything using it loses access right away, and this can’t be undone.

API keys page listing keys with their environment, scope count, status, key prefix, created, last used and expiry dates
API keys in project settings

Good to know

  • The list shows each key’s first characters and its status: Active, Expired or Revoked.
  • A key set to Never still expires after 90 days, so plan to replace keys regularly.
  • Revoked keys are hidden until you turn on Show revoked.