DocsAPI authenticationAPI keys

API keys

Create, scope, use, rotate, and revoke personal or service API keys for authenticated Lifecycle v2 requests.

API keys give scripts and integrations access with scope limits to Lifecycle’s v2 API. Use a personal key for work attributable to one user and a service key for a shared automation identity.

Create a personal key

  1. Open Settings.
  2. Open My API keys.
  3. Enter a name that identifies the caller and purpose.
  4. Grant only the scopes necessary for the caller.
  5. Select All repositories or select up to 50 repositories.
  6. Select an explicit expiration.
  7. Create the key.
  8. Copy the key from the one-time result.
  9. Store the key in an approved secret manager.
  10. Close the result.

Personal key values begin with lfc_pat_. Lifecycle shows the full value only at creation. By default, each user can have 10 active personal keys. An administrator can change this limit.

If you reach the active key limit, revoke a previous key. Then, create the new key.

Administrators use Settings → API key management:

  • Use Service keys to create or revoke automation identities.
  • Use User keys to examine or revoke personal keys.
  • Use Access controls to set authentication, issuance, scope policy, repository policy, and rate limits.

Service key values begin with lfc_svc_. Lifecycle reveals them only at creation.

Select scopes

Lifecycle recognizes seven scopes:

ScopeAccess
env:readRead Environments and Builds
env:writeCreate or change Environments and Builds. Also satisfies env:read
sites:readRead sites. sites:write satisfies this scope.
sites:writeUpload, replace, extend, or delete sites
repos:readRead repository information. repos:write satisfies this scope.
repos:writeChange supported repository configuration
env:adminLegacy/reserved Environment administration

New keys can request only the first six scopes. A legacy service key can keep env:admin. You cannot grant this scope to a new key.

Write implies read only for the same resource. For example, env:write does not grant sites:read.

⚠️

All repositories is an explicit broad grant. Prefer a selected repository list, especially for CI. An empty selected list does not mean all repositories.

Select an expiration

The personal-key policy defaults to a 168-hour (7-day) selection and caps finite personal keys at 720 hours (30 days). An administrator can decrease the available UI options. The running deployment’s policy controls the active key limit, available expirations, scopes, and repository constraints.

If you do not send ttlHours and expiresAt, the API creates a non-expiring key. Omission does not mean the UI default. Always send or select an explicit finite expiration. An approved service-key policy can specify a different expiration.

Key check

Use the v2 authentication context without exposing the key value:

Before you use the key in automation, make sure of its type, scopes, repository constraint, and expiry.

Lifecycle applies a rate limit to API-key requests. The default limit is 600 requests per minute. Lifecycle aggregates requests by key owner. An administrator can change the limit. Honor Retry-After on a 429 response.

Management routes

PurposeAuthenticated v2 route
My key policyGET /api/v2/me/tokens/policy
List or create my keysGET or POST /api/v2/me/tokens
Revoke one of my keysDELETE /api/v2/me/tokens/{id}
List or create service keysGET or POST /api/v2/tokens
Revoke a managed keyDELETE /api/v2/tokens/{id}

Personal management routes accept only the user’s browser session. Service-key management routes accept only an administrator session. For request and response schemas, use the running deployment’s generated API reference.

Rotate a key after exposure

  1. Create a replacement with the smallest scopes and repository set.
  2. Update the caller through its secret manager.
  3. Make sure that the replacement works with /api/v2/auth/context.
  4. Revoke the previous key.
  5. If you think that a key leaked, revoke it immediately.
  6. Tell an administrator to examine the API and key-management audit events.

If the full key is not available, Lifecycle cannot show it. Create a replacement.

API authenticationLifecycle API overview