Token exchange
A workload gets a KERNEL access token by posting its identity token to the KERNEL authorization server. The SDKs make this request for you.Request
POST https://auth.onkernel.com/token takes a form-encoded body and no credential.
The endpoint is strict about what it accepts:
- Any other parameter, including
client_idandclient_secret, is rejected. - A parameter sent twice is rejected.
- A request with an
Authorizationheader is rejected. The identity token is the only proof.
Response
There’s no refresh token. To get another access token, exchange a fresh identity token.
Access token lifetime
The access token expires at the earliest of:- The rule’s token lifetime (
max_token_ttl_seconds): 300 seconds by default, 600 at most. - The identity token’s own expiry.
Errors
Errors use the OAuth error format, with anerror code and an error_description.
The endpoint doesn’t say why a token was refused, so that a caller can’t probe your configuration. See Troubleshooting to find the reason.
Discovery
A client can find everything it needs from the API host:GET https://api.onkernel.com/.well-known/oauth-protected-resourcereturnsresource, the exact value to send as theresourceparameter, andauthorization_servers, which names the authorization server.GET https://auth.onkernel.com/.well-known/oauth-authorization-serverreturns thetoken_endpoint, and listsurn:ietf:params:oauth:grant-type:jwt-bearerundergrant_types_supported.
SDK configuration
Federation support is in@onkernel/sdk for TypeScript, the kernel package for Python, and github.com/kernel/kernel-go-sdk for Go. The Go SDK needs Go 1.23 or later.
Environment variables
When
KERNEL_IDENTITY_TOKEN_SOURCE isn’t set, the SDK uses the first of these that applies:
KERNEL_IDENTITY_TOKEN_FILEKERNEL_IDENTITY_TOKEN- GitHub Actions, when the runner exposes
ACTIONS_ID_TOKEN_REQUEST_URL
KERNEL_IDENTITY_TOKEN_SOURCE to aws_sts or gcp_metadata.
Credential precedence
When
KERNEL_API_KEY and KERNEL_FEDERATION_RULE_ID are both set, the SDK uses the API key and logs one warning.
The SDKs differ in two edge cases:
Identity token sources
Import the TypeScript names from
@onkernel/sdk/lib/credentials, the Python names from kernel, and the Go names from github.com/kernel/kernel-go-sdk/lib/credentials, its awssts subpackage, and github.com/kernel/kernel-go-sdk/option.
The built-in sources request a token for this audience: the source’s own audience setting, then KERNEL_IDENTITY_TOKEN_AUDIENCE, then the auth base URL.
Federation options
Pass these with the identity token source: tooidcFederationProvider in TypeScript, WorkloadIdentityCredentials in Python, and option.FederationOptions in Go.
If you point the client at a base URL other than
https://api.onkernel.com, you must also set the auth base URL. The SDK refuses to pair a custom API with the default authorization server.
Exchange a token once
To manage the access token yourself, call the exchange directly. It makes one request, caches nothing, and needs no KERNEL credential:expiresAt and expires_at are Unix seconds. In Go, ExpiresAt is a time.Time. Python also has async_exchange_federation_assertion.
The call spends the identity token. Don’t call it again with the same token, even after a timeout.
Refresh and retries
- The SDK caches the access token and shares it between copies of a client that use the same base URL.
- It refreshes in the background when less than 120 seconds, or 40% of the token’s lifetime if that’s shorter, remains.
- It blocks requests on a refresh when less than 30 seconds, or 10% of the lifetime, remains.
- Concurrent requests share one exchange. The identity token source is never called twice at once.
- A
401from the API drops the cached token and retries the request once with a token from a fresh exchange. A second401is returned to you. A request whose body can’t be sent again isn’t retried. In Python, a client withmax_retries=0doesn’t retry a401at all.
Errors
A failed exchange or a misconfiguration surfaces as aWorkloadIdentityError.
For a token that was already exchanged, the message adds advice that depends on where the token came from: a file that wasn’t rotated, a static value, or a callback that returned the same token.
Safeguards
The SDKs protect the identity token in transit:- The token endpoint must be
https. Plainhttpis allowed only forlocalhost,127.0.0.1, and::1. - An identity token over 16 KiB is refused before it’s sent.
- Token requests don’t follow redirects.
- Errors and logs never include the identity token or the access token.
Issuers
An issuer (wii_...) registers one identity provider.
Provider types
The supported algorithms are
RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, ES512, and EdDSA.
GitHub Actions, Google Cloud, and Microsoft Entra issuers are recognized by their issuer URL and must use their own type. You can’t register https://accounts.google.com as custom_oidc to skip Google’s identity checks.
Key sources
- Keys are fetched over
httpsfrom public internet addresses only. ca_cert_pemreplaces the system root certificates for that fetch. It holds public CA certificates only.- A key set holds at most 16 keys, all public. RSA keys must be at least 2,048 bits.
- Fetched keys are cached for five minutes. A token that names an unknown key ID triggers a new fetch, at most once a minute.
- GitHub Actions issuers always use discovery.
How a token is verified
KERNEL accepts an identity token only when:- It’s a signed JWT of 16 KiB or less, and its signature verifies against one of the issuer’s keys.
issequals the issuer URL exactly.audholds exactly one value, equal to the rule’sexpected_audience.subis a non-empty string of 1,024 characters or less.expandiatare both present, the token hasn’t expired, andexpminusiatis withinmax_lifetime_seconds. KERNEL allows 30 seconds of clock difference.- For a single-use issuer, the token has a token ID that hasn’t been exchanged before. The token ID is
jti, orutifor Microsoft Entra. - The rule’s match conditions all hold.
Federation rules
A federation rule (wifr_...) maps tokens from one issuer to one service account, one project, and one policy.
Match fields
match.type must equal the issuer’s preset_type. Every condition a rule sets must hold.
These fields are available for every type:
GitHub Actions
AWS and custom OIDC
At least one ofsubject, subject_prefix, or claims is required. For AWS, subject is the IAM role ARN, including its path.
Google Cloud
Microsoft Entra
At least one of these is required:subject, or a claims condition on /oid, /appid, or /azp.
- KERNEL adds a
/tidcondition for the issuer’s tenant. A rule that names a different tenant is rejected. - A rule with no
subjectand no/oidalso requires/idtypto beapp. - A token with an
scpclaim never matches.
Kubernetes
The token’s subject must be exactly
system:serviceaccount:<namespace>:<service_account>.
Service accounts
See Service accounts.
Authentication events
Each event records one exchange outcome. Events never hold tokens or claims.
A failure is recorded only after the token has verified and matched an enabled rule. A token that fails signature, issuer, audience, expiry, or match checks leaves no event, because KERNEL can’t yet tie it to your organization. Repeated failures for the same token and reason are recorded once.
Events are kept for 30 days. Through the API, a query returns the last seven days by default and spans at most 30 days. You can filter by issuer, rule, service account, project, outcome, and time range.
Auth context
GET https://api.onkernel.com/auth/context describes the credential that makes the request. For a federated token, it returns the service account, the project, the current policy, and which issuer and rule the token came from:
external_subject_digest is a digest of the identity token’s subject. The token and its claims are never returned. A service account API key gets the same response without workload_identity, and with authentication.method set to api_key.
The call needs no permission in the policy.
Management API
Manage service accounts, issuers, and rules in the dashboard. These are the endpoints behind it, listed for reference. They aren’t currently accessible with an API key or a federated token: a call with either returns403, including through the SDK methods for these endpoints.
Who can manage them
- Any organization member can view service accounts, issuers, rules, and authentication events.
- Only an organization admin can change them: create, update, archive, and verify.
Updates and versions
Every resource has asecurity_version that increases when a change affects what it trusts or grants. An update (PATCH) must send the version it’s based on as expected_version. If the resource changed in the meantime, the update returns 409 Conflict. Read the resource again and retry.
Lists and archiving
- Lists take
limit(1 to 100, default 20) andoffset, and returnX-Has-MoreandX-Next-Offsetheaders. Service account, issuer, and rule lists also takestatus:active(the default),archived, orall. DELETEarchives. History stays, and the archived resource stops granting access. Creating a resource with the same name or issuer URL later creates a new ID.- A problem the admin can fix, such as a key endpoint that isn’t public or a discovery document that names a different issuer, returns
400with the reason. A503means a condition that may pass on retry, such as a timeout.