Skip to content

Get an access token for an application

Obtain the access token an application presents on every cryptographic call, check whether a token is still active, and end it before it expires.

Who can do it

  • The application itself obtains its token. It authenticates as a cryptographic actor of your tenant with that actor's credential; no role is involved.
  • Any holder of a token can revoke it, and only a token issued to itself. An administrative workload's token is refused here.
  • Checking whether a token is active (introspection) needs the permission to read tokens. The built-in tenant administrator, access administrator, key manager, auditor and viewer roles hold it for their own tenant. The platform roles reach every tenant only on a private-cloud or on-premise deployment; on SaaS they introspect nothing.

Before you start

  • The application has a cryptographic actor with a credential: a shared secret, which the console shows once when it is issued, or a registered key pair whose private key stays with the application. A tenant administrator issues it on the actor's Credentials tab in Cryptographic Actors.
  • The actor has at least one role. An actor without a way to authenticate and a role cannot operate.
  • You know the address of the ANKASecure deployment.

Steps

  1. Give the application its credential without writing the secret on a command line:
    • Java SDK: set anka.auth.clientId and anka.auth.clientSecret in the properties you pass to AnkaSecureSdk, or the environment variables ANKASECURE_CLIENT_ID and ANKASECURE_CLIENT_SECRET. For a registered key pair, set anka.auth.actorKeyFile and anka.auth.expectedAudience instead.
    • Crypto CLI: run AnkaSecureCLI init --url <deployment-url> --client-id <actor-id> --client-secret. The --client-secret flag takes no value: the CLI prompts for the secret, or reads ANKASECURE_CLIENT_SECRET with --silent. A key pair is declared with --actor-key-file and --expected-audience.
  2. Authenticate:
    • Java SDK: new AnkaSecureSdk(properties).authenticate() resolves the configured credential and returns an AuthenticatedSdk. authenticateApplication(clientId, clientSecret) and authenticateApplicationWithKeyPair(clientId, signer, expectedAudience) take the credential directly.
    • Crypto CLI: every command authenticates with the stored credential. AnkaSecureCLI view-session shows the configured deployment and credential.
    • API: POST /api/v3/auth/token with an application/x-www-form-urlencoded body grant_type=client_credentials&client_id=<actor-id>&client_secret=<secret>. For a registered key pair, send client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer and a freshly signed client_assertion instead of the secret, never both. Send the secret in the body, never in the query string.
  3. If the actor works under an exchange context, add exchange_context=<context-id> to the token request. The token is then bound to that context.
  4. Send the token as Authorization: Bearer <access_token> on every call. The SDK does this for you and obtains a new token when the current one is within 60 seconds of its expiry.
  5. To check a token, call POST /api/v3/auth/token/introspect with the form body token=<token>, authenticated as a person or workload that holds the permission to read tokens.
  6. To end a token before it expires, call POST /api/v3/auth/token/revoke with the form body token=<token>, authenticated with a token of the same holder. In the SDK, close() on the AuthenticatedSdk discards the token and the stored credential copy from memory.

What you see when it worked

The token request answers 200 with access_token, token_type Bearer and expires_in, the lifetime in seconds. No refresh token is issued to an application: it requests a new token with its credential.

Introspection answers {"active": true, ...} with the token's claims for an active token of a tenant you may read. Revocation answers 200 with an empty body, and the revoked token appears in Token Management as a revoked entry until it would have expired.

If it fails

What you see Cause What to do
401 with error invalid_client The credential was refused: an unknown actor, a wrong, revoked or expired credential, or a disabled actor. Every cause gets the same answer Check the actor and its credential in Cryptographic Actors; issue or rotate a credential if needed
400 invalid_request naming a parameter that is not accepted in the request URI The secret or another credential was sent in the query string Send it in the form body
400 invalid_request on a request with exchange_context The actor holds no live Capability Grant bound to that context in its tenant, or the context is closed Use a context the actor holds a grant in, or omit the parameter
429 with Retry-After Too many token requests from one source in one minute Wait the indicated time, and reuse a token until it nears expiry
503 (temporarily_unavailable, token-signing-unavailable or dependency-not-ready) The service cannot issue a token right now; nothing was decided about the credential Retry after Retry-After
502 or 504 The service that verifies credentials could not be reached or did not answer in time; nothing was decided about the credential Retry later
A call answers 401 although the token has not expired The token was revoked, or every token of its holder was invalidated Authenticate again; the SDK raises TokenRevokedException
Introspection answers {"active": false} The token expired, was revoked, belongs to another tenant or never existed. The answer does not say which Obtain a new token
Introspection answers 403 The caller does not hold the permission to read tokens Introspect as a person or workload that holds it

Without the console

The console uses the token endpoint to sign people in and the sign-out operation to end their session; an application uses neither screen. Every step above is an SDK, CLI or API call.

Surface How
Java SDK AnkaSecureSdk.authenticate(), authenticateApplication(...), authenticateApplicationWithKeyPair(...); AuthenticatedSdk.close()
Crypto CLI AnkaSecureCLI init, AnkaSecureCLI view-session
API POST /api/v3/auth/token (operation createToken), POST /api/v3/auth/token/introspect (introspectToken), POST /api/v3/auth/token/revoke (revokeToken)