DocsTroubleshootingTroubleshoot access and API errors

Troubleshoot access and API errors

Diagnose Lifecycle sign-in, GitHub linking, API key, scope, repository, and feature-policy failures while credentials stay secret.

Keep browser identity, linked GitHub identity, API-key authorization, and feature policy as different concepts. They are related but not interchangeable.

Cannot sign in

  1. Make sure that the UI and identity hostnames resolve and have valid TLS.
  2. Use the identity provider configured by your Lifecycle operator.
  3. If using the bundled temporary bootstrap account, complete the necessary first-login password change.
  4. Give the operator the time, browser-visible error, and request ID. Do not send a password, session cookie, authorization code, or token.

If the deployment has authentication disabled, do not work around the error by exposing it to a shared network. Auth-off mode is only an isolated local evaluation posture.

Signed in but GitHub features are missing

A successful sign-in does not link a GitHub user. Use the Link GitHub prompt or the Account or Settings connection control. A linked user is also different from:

Examine the three relationships for repository creation, attribution, and Agent Git operations.

API returns 401

  • Make sure that the header uses Authorization: Bearer <token>.
  • When you created the key, you had to copy its plaintext value. Lifecycle cannot retrieve the key again.
  • Make sure that the key was not revoked or expired.
  • Make sure that the deployment has supported authentication and API-key issuance enabled.
  • Record only the non-secret token prefix and key ID—not the token.

API returns 403

  • Make sure that the key type can request the necessary scope.
  • Examine scope implication: write includes read for the same resource.
  • Examine selected-repository access and repository onboarding.
  • Examine the administrator’s feature switch for API keys, API Environments, or Sites.
  • Remember that a reachable endpoint does not bypass its policy gate.

Use the authenticated v2 auth-context endpoint described in API keys to examine the resolved principal without printing a credential.

API returns 429

The API-access default is 600 requests per minute. Administrators can change this policy. When the response contains Retry-After, respect its value. Use pagination. Do not poll faster than necessary for the task. Use idempotency keys for create requests that support them.

Missing PR commentUse the Mission Control comment