Deployments.ai Docs
Platform

Service accounts and API keys

Machine identities and the API keys they use, including scopes, rotation, revocation, and usage records.

A service account is a machine identity that belongs to one environment. An API key is the bearer secret a service account uses to call the API. Use them for backend services, CI jobs, and any automation that should not run under a person's sign-in.

The model

ResourceBelongs toHoldsStatuses
Service accountOne environmentname, description, and a list of capability scopesactive, disabled
API keyOne service accountname, scopes, optional expiresAt, and a keyPrefixactive, revoked

A key's secret starts with dpl_. The platform stores only a SHA-256 hash of it. The keyPrefix field holds the first 16 characters so you can tell keys apart in lists.

Scopes narrow at every step

  • A service account needs at least one scope. Its scopes must be a subset of the scopes held by the caller who creates it.
  • An API key takes its service account's scopes by default. If you list scopes, they must be a subset of the service account's scopes.
  • On each request, the key's effective scopes are the key's scopes that the service account also holds.

Scopes use the form namespace:level, for example runs:write. namespace:* covers every level of a namespace. API keys have one exception. A key holds apps:publish only when its scopes and its service account's scopes both name it, and neither apps:* nor platform:* grants it to a key, as agent-built apps explains. For the same reason, a key can give apps:publish to a new service account or key only when the key names it. Core concepts lists how scopes and roles interact. Service accounts have no organization role. Where a person also needs an organization role to make a change, a key needs only the scope. Updating the organization and listing or managing its members and invitations always require an organization role, so a key cannot do them.

A key works only in its environment

A key carries its organization, project, and environment. It can reach only that environment. Runtime operations accept a key without tenant headers. If you send tenant headers with a key, they must match the key's environment.

A key stops authenticating when any of these is true:

  • The key is revoked.
  • The key's expiresAt has passed. The key's status stays active.
  • Its service account is revoked.

Rotation replaces the secret in place

Rotating a key issues a new secret for the same key ID and replaces the stored hash in one write. The old secret stops working at once, so deploy the new secret before you rotate a key in use, or create a second key, switch to it, and revoke the first. You can rotate only an active key whose service account is active.

Revoking a key or a service account is final. Revoking one that is already revoked returns it unchanged. Revoking a service account sets its status to disabled, and all of its keys stop authenticating.

Secrets appear once

The create and rotate responses include the secret and secretVisibleOnce: true. No later call returns it. The CLI hides the secret in its output unless you pass --reveal.

Required scopes and roles

OperationScope
List or show service accountsservice-accounts:read
Create or revoke a service accountservice-accounts:write
List API keysapi-keys:read
Create, rotate, or revoke a keyapi-keys:write
Read API key usageapi-keys:read

For people, the write scopes also require the owner or admin role in the organization.

Use it

Create a service account with the scopes your automation needs:

deployments service-account create --name "release-bot" --scopes agents:read,agents:write,runs:read,runs:write

Copy the service account id.

Create a key and capture the secret. Write it straight into your secret store:

deployments api-key create --name "release-bot-ci" --service-account $SERVICE_ACCOUNT_ID --reveal --json

To limit the key further, pass --scopes. To make it expire, pass --expires with a UTC timestamp.

Use the key. The CLI reads it from DEPLOYMENTS_API_KEY:

DEPLOYMENTS_API_KEY=$RELEASE_BOT_KEY deployments whoami --live

whoami returns authentication api-credential, the service account ID as id, and the key's effective capabilities.

Review what the key has been doing. Each record has the request method and path, an outcome of allowed, denied, or error, and a timestamp:

deployments api-key usage --api-credential $API_KEY_ID --since 2026-10-01T00:00:00.000Z

Rotate or revoke the key:

deployments api-key rotate $API_KEY_ID --reason "Scheduled rotation" --reveal
deployments api-key revoke $API_KEY_ID --reason "Pipeline retired"

From TypeScript, pass the key as a bearer token:

import { createClient, createConfig, listAgentDeployments } from "@deployments-ai/sdk";

const client = createClient(
  createConfig({
    baseUrl: "https://api.example.com",
    headers: { authorization: `Bearer ${process.env.DEPLOYMENTS_API_KEY}` },
  }),
);

const { data, error } = await listAgentDeployments({
  client,
  headers: { "x-deployments-environment": process.env.ENV_ID! },
});

Reference

On this page