Skip to Content
Platform
Identity and AccessCredentials

Credentials

Your backend authenticates with an API credential: an API key or a service account.

An API credential lets your code call Introspection for one project and one environment. Use an API key first; move to a service account when you need short-lived tokens or a browser token broker.

You need: a login to the project (introspection login).

The agent’s own secrets (model keys, bot tokens, user connections) are not API credentials; they live in Bindings.

Create an API key

  1. Create the key. The secret is written to the file, never printed: 
    introspection api-keys create --name ci --environment staging --secret-file ./introspection-key.txt
    Or use Project settings, API keys.
  2. Copy the secret from that file into your backend’s secret store as INTROSPECTION_TOKEN, which the SDK and CLI read. Then delete the file.
  3. Verify with introspection api-keys list.
PropertyValue
EnvironmentFixed at creation; a staging key cannot reach production
Acts asThe Member Agent by default (--member-id for the Admin Agent)
Capabilitiesruntimes (default) and evals
SecretShown once; Introspection keeps only a hash
CannotAdminister members, applications, or integrations

An API key never belongs in a browser, a mobile binary, an agent sandbox, or anywhere an end user can read it.

Use the CLI with an API key

Data Plane commands accept --token or INTROSPECTION_TOKEN: tasks, conversations, events, metrics, files, shares, tags, images, annotations, and repository reads. Control Plane commands (runtimes, bindings, connectors, applications, api-keys, members, experiments, judges) always act as your login (full table).

The key’s environment selects where Data Plane work runs. It does not make the CLI read-only: a production key can still create and delete tasks, upload files, and create shares (deleting files needs a key with the evals capability; no key can delete shares).

Create a service account

  1. Create it: introspection applications create --type service-account --name "Acme backend".
  2. Mint a client secret (shown once): introspection applications secrets create --app <application-id>.
  3. Your backend exchanges the client ID and secret (client_credentials) for an access token. The SDK call is in Authentication.

Access tokens last 60 minutes and have no refresh token. The JS fromServiceAccount client does not refresh, so mint a new token before expiry.

The SDK’s telemetry exporters (track, feedback, OTLP logs) keep the token they start with, so a long-running exporter needs an API key.

Rotate or revoke a credential

introspection api-keys revoke --key <key-id> --expires-in 3600
introspection applications secrets revoke --app <application-id> --secret <secret-id> --expires-in 3600

--expires-in gives callers a grace period; omit it to revoke now. To change a key’s environment, create a new key and revoke the old one.

Next

Last updated on