DocsAPI authenticationAPI authentication

API authentication

Select a supported authentication method for Lifecycle v2 API requests and understand typical authorization failures.

Lifecycle’s v2 API authenticates interactive users with an OIDC session and programmatic callers with API keys. Some routes accept only one of these methods.

⚠️

API keys operate only with deployment authentication. The operator must also enable issuance and key authentication. Do not expose Lifecycle by turning authentication off. See Authentication for deployment security requirements.

Select an authentication method

CallerMethodUse
Browser UIOIDC sessionInteractive use and administrator-only session routes
Script, CI job, or integrationAPI keyProgrammatic v2 routes allowed by the key’s scopes

An API key does not replace an administrator browser session. Some configuration routes accept only a session. Broad key scopes do not change this restriction.

Send an API key

Store the key in your approved secret manager and send it as a bearer credential:

Do not print the environment variable, pass the key in a query string, commit it to a repository, or paste it into documentation.

The authentication context reports how Lifecycle interpreted the caller. It reports resolved roles, scopes, and repository constraints. Use it as the first check after issuing or rotating a key.

Understand failures

  • 401 Unauthorized means Lifecycle could not authenticate the credential. The key can be missing, malformed, revoked, or expired. The policy can disable the key.
  • 403 Forbidden means Lifecycle recognized the credential, but the necessary role, scope, repository access, or enabled feature is not available.
  • 429 Too Many Requests means the key owner exceeded the configured API-key rate limit. Honor Retry-After.

Do not disable authentication for a 401. Rotate or correct the credential.

Continue with API keys and API overview.

Use the Lifecycle UIAPI keys