Skip to main content
The token endpoint doesn’t say why it refused a token. That’s deliberate: a caller without valid proof learns nothing about your configuration. This page shows how to find the reason from your side.

Start here

1

Read the SDK error

The SDK raises a WorkloadIdentityError with the HTTP status, the OAuth error code, and a description. Match it against the table below.
2

Check the authentication events

In the dashboard, open Keys > Workload identity > Authentication events and filter by Rule.
  • A failure event exists. The token verified and matched the rule, and the reason says what went wrong next.
  • No event exists. The token was refused before KERNEL could tie it to your organization: the signature, issuer, audience, expiry, or match conditions didn’t hold, or the rule or issuer isn’t enabled.
3

Decode the token

Print the identity token’s claims from inside the workload and compare them with the rule:
Check iss against the issuer URL, aud against the rule’s expected audience, and sub and the other claims against the rule’s match conditions. Don’t paste a live token into a website or a chat.

Exchange errors

The same token was sent twice

GitHub Actions and AWS tokens can be exchanged once. Microsoft Entra and custom OIDC tokens can be exchanged once unless you allow reuse. When a token is presented a second time, the SDK’s message says where it came from: To allow reuse on a Microsoft Entra, Kubernetes, or custom OIDC issuer, select Edit on the issuer and turn off Enforce single-use tokens (JTI replay protection). A reusable token can be exchanged until it expires, so allow reuse only when your token source needs it.

SDK configuration problems

Requests fail after a successful exchange

Provider notes

GitHub Actions
  • A rule needs a branch or an environment. A job on another branch, or without that environment, doesn’t match.
  • pull_request, schedule, and release events aren’t allowed unless you add them to Allowed events.
  • A rule with a Workflow path matches only when the workflow file comes from the same ref the job runs on.
  • The rule pins numeric repository and owner IDs. A repository that was deleted and recreated under the same name has a new ID.
AWS
  • The subject is the IAM role ARN with its path, such as arn:aws:iam::123456789012:role/service/browser-worker.
  • GetWebIdentityToken isn’t served by the global STS endpoint. The SDKs call the regional endpoint for AWS_REGION.
Google Cloud
  • The subject is the service account’s numeric unique ID, not its email.
  • The metadata server returns a token for the service account attached to the workload. Check that it’s the one your rule names.
Microsoft Entra
  • A token with an scp claim was issued to a signed-in user and never matches. Use a managed identity or client credentials.
  • v1.0 and v2.0 tokens have different issuers and audiences. Register the issuer version your tokens carry.
  • A rule keyed only on a client ID needs the idtyp optional claim. See Microsoft Entra.
Kubernetes
  • The default service account token has the wrong audience. Mount a projected token with the audience https://auth.onkernel.com.
  • A projected token with expirationSeconds over 3,600 exceeds the issuer’s default maximum lifetime.
  • KERNEL must reach the cluster’s discovery document and keys from the public internet. For a private cluster, upload the keys.

Issuer key problems

Check signing keys on the Issuers tab fetches the issuer’s keys and reports the result. When KERNEL can’t use the keys for a reason you can fix, it tells you which:
  • The key endpoint’s address isn’t on the public internet.
  • The endpoint returned the wrong status or didn’t return JSON.
  • The discovery document names a different issuer than the one you registered.
  • The key set isn’t valid or holds an unsupported key.
A timeout or other temporary condition is reported as unavailable. Try again.

Still stuck

Contact support with the rule ID, the time of the attempt, and the request ID from the SDK error if there is one. Don’t send the identity token or the access token.