Package co.ankatech.keymanagement.client.auth.api

Class TokenManagementApi

java.lang.Object
co.ankatech.keymanagement.client.auth.api.TokenManagementApi
public class TokenManagementApi extends Object

  • Constructor Details

    • TokenManagementApi

      public TokenManagementApi()

    • TokenManagementApi

      public TokenManagementApi(ApiClient apiClient)

  • Method Details

    • getApiClient

      public ApiClient getApiClient()

    • setApiClient

      public void setApiClient(ApiClient apiClient)

    • getHostIndex

      public int getHostIndex()

    • setHostIndex

      public void setHostIndex(int hostIndex)

    • getCustomBaseUrl

      public String getCustomBaseUrl()

    • setCustomBaseUrl

      public void setCustomBaseUrl(String customBaseUrl)

    • createTokenCall

      public okhttp3.Call createTokenCall(@Nonnull String grantType, @Nullable String dpoP, @Nullable UUID tenantId, @Nullable String clientId, @Nullable String clientSecret, @Nullable String clientAssertionType, @Nullable String clientAssertion, @Nullable UUID exchangeContext, @Nullable String refreshToken, @Nullable String subjectToken, @Nullable URI subjectTokenType, @Nullable URI requestedTokenType, @Nullable URI resource, @Nullable String scope, @Nullable String code, @Nullable String codeVerifier, @Nullable String maxAge, @Nullable String rememberMe, ApiCallback _callback) throws ApiException
      Build call for createToken
      Parameters:
      grantType - OAuth 2.0 grant type per RFC 6749. Determines which authentication flow to use. Supported values: - authorization_code: Redeems the authorization code a sign-in at the authorization challenge endpoint ended in, with its PKCE code_verifier (RFC 6749 Section 4.1.3, RFC 7636) - client_credentials: Application authentication with client_id/client_secret (RFC 6749 Section 4.4) - refresh_token: Token refresh using refresh token, optionally switching tenant (RFC 6749 Section 6) - urn:ietf:params:oauth:grant-type:token-exchange: Token exchange for impersonation (RFC 8693) (required)
      dpoP - A DPoP proof (RFC 9449 §4), JWS compact serialization. Sent by an administrative workload with grant_type=client_credentials to obtain a DPoP-bound token; exactly one such header. Absent on every other request. (optional)
      tenantId - Tenant UUID. - refresh_token: OPTIONAL. Another ACTIVE membership of the same identity to switch to; absent or equal to the session's tenant, the session refreshes its own tenant. (optional)
      clientId - grant_type=client_credentials: REQUIRED. The UUID of the cryptographic ACTOR or administrative workload that holds the credential and is authenticating. An APPLICATION groups actors, holds no credential and cannot authenticate, so its id is never presented here. A person's grants (authorization_code, refresh_token) send none. (optional)
      clientSecret - Application secret. REQUIRED when grant_type=client_credentials. The secret credential for the application, validated against the stored hash. Minimum 8 characters. This secret is generated when the application is created and should be stored securely (environment variables, secret manager). (optional)
      clientAssertionType - Which assertion profile the client_assertion follows. REQUIRED when client_assertion is present. Two values are admitted: - urn:ietf:params:oauth:client-assertion-type:jwt-bearer (RFC 7523 §2.2) — the actor signed the assertion itself, with a key registered for it here. - urn:ankatech:params:oauth:client-assertion-type:federated-jwt — an external issuer this deployment trusts minted the token for the workload, and an (issuer, subject) declaration binds it to the actor named by client_id. This declared value is the ONLY thing that selects between them. The token's own contents are never inspected to make that choice. An unrecognised value is a 400 invalid_request, not a credential failure: the client asked for a profile this server does not implement, which is a malformed request rather than a wrong credential. (optional)
      clientAssertion - The assertion, in JWS compact serialization. REQUIRED when grant_type=client_credentials and the actor authenticates with an assertion rather than a shared secret. Bounded at 16 KiB; a larger value is refused as a credential failure, indistinguishably from any other. Under jwt-bearer the actor signed it: iss and sub are both the actor UUID, aud is the audience this deployment returned when the key was registered, and jti is single-use. Under federated-jwt an external issuer signed it: iss is that issuer, sub is the workload subject bound to the actor, aud is the audience this deployment derived for the issuer, and jti is optional. (optional)
      exchangeContext - OPTIONAL Exchange Context UUID for grant_type=client_credentials when the client_id is a Cryptographic Actor. The issued JWT carries the supplied value in the exchangeContextId claim, binding the token to operations conducted under that Exchange Context. Omit this parameter for Actors that operate without a specific Exchange Context (internal operations) — the emitted JWT then carries null exchangeContextId and the cryptographic service will match grants that also have null exchange_context_id. (optional)
      refreshToken - Opaque refresh token for grant_type=refresh_token. A person's session presents it in the httpOnly refresh cookie, or here, without a client_id. If both are present, this parameter takes precedence. (optional)
      subjectToken - JWT access token to exchange. REQUIRED when grant_type=urn:ietf:params:oauth:grant-type:token-exchange. This is the platform admin's JWT token that will be exchanged for a tenant-scoped token. The token must have platform-level privileges to perform impersonation. Format: JWT with RS256 signature. (optional)
      subjectTokenType - Type of subject_token per RFC 8693. OPTIONAL for token exchange. Standard value: urn:ietf:params:oauth:token-type:access_token If omitted, defaults to access_token type. (optional)
      requestedTokenType - Type of requested token per RFC 8693. OPTIONAL for token exchange. Standard value: urn:ietf:params:oauth:token-type:access_token If omitted, defaults to access_token type. (optional)
      resource - Target tenant URI for impersonation. REQUIRED when grant_type=urn:ietf:params:oauth:grant-type:token-exchange. Format: urn:ankatech:tenant:<tenant-uuid> Example: urn:ankatech:tenant:00000000-0000-0000-0000-000000000003 This identifies which tenant the impersonation token should target. The platform admin will receive a token with tenant-scoped privileges. (optional)
      scope - Space-delimited list of requested scopes. OPTIONAL for all grant types. Accepted and ignored: the issued token carries the scopes its subject's role assignments grant, whatever this parameter requests. A value here neither narrows nor widens them, and is never an error. (optional)
      code - The authorization code of a completed sign-in at the authorization challenge endpoint. REQUIRED when grant_type=authorization_code. Valid for 60 seconds and consumed by its first presentation, whatever the outcome: a second presentation, a wrong code_verifier or an expired code is invalid_grant. (optional)
      codeVerifier - The PKCE code_verifier whose S256 challenge started the sign-in (RFC 7636 Section 4.5). REQUIRED when grant_type=authorization_code. 43 to 128 characters of [A-Z a-z 0-9 - . _ ~]. (optional)
      maxAge - The oldest proof of identity, in seconds, the refreshed session may rest on (OIDC Core 1.0 max_age). OPTIONAL, and accepted only when grant_type=refresh_token without a switch to another tenant. A non-negative integer. When the session's most recent authentication for its tenant is older, the refresh is answered 403 insufficient_authorization with an auth_session that continues a fresh reauthentication at the authorization challenge endpoint; nothing is rotated. (optional)
      rememberMe - Remember this sign-in. OPTIONAL when grant_type=authorization_code. Values: - true: the refresh cookie is persistent, with a Max-Age equal to the seconds left to the session's absolute expiry, and the longer Remember Me inactivity window applies (auth.session.remember-me.inactivity-timeout-minutes). Ignored while auth.session.remember-me.enabled is false. - false or omitted: the refresh cookie is a session cookie and the standard inactivity window applies (auth.session.inactivity-timeout-minutes). Remember Me never extends the session's absolute expiry (auth.session.absolute-lifetime-minutes). Only applies to the authorization_code grant; refreshes keep the session's choice. (optional, default to false)
      _callback - Callback for upload/download progress
      Returns:
      Call to execute
      Throws:
      ApiException - If fail to serialize the request body object

    • createToken

      public TokenResponse createToken(@Nonnull String grantType, @Nullable String dpoP, @Nullable UUID tenantId, @Nullable String clientId, @Nullable String clientSecret, @Nullable String clientAssertionType, @Nullable String clientAssertion, @Nullable UUID exchangeContext, @Nullable String refreshToken, @Nullable String subjectToken, @Nullable URI subjectTokenType, @Nullable URI requestedTokenType, @Nullable URI resource, @Nullable String scope, @Nullable String code, @Nullable String codeVerifier, @Nullable String maxAge, @Nullable String rememberMe) throws ApiException
      OAuth 2.0 token endpoint (RFC 6749/8693) OAuth 2.0 token endpoint supporting five grant types. **Request Format:** application/x-www-form-urlencoded (OAuth 2.0 standard) **Supported Grant Types:** - authorization_code: Redeems the authorization code a sign-in at POST /api/v3/auth/authorize-challenge ended in, with its PKCE code_verifier (RFC 6749 Section 4.1.3, RFC 7636 Section 4.5). The code is valid for 60 seconds and is consumed by its first presentation; a second presentation, a wrong code_verifier or an expired code is invalid_grant. The answer is the session of the tenant the sign-in admitted; `amr` names the methods of the authority that admitted the membership (`user` and `hwk` or `swk` for a passkey; the methods the OIDC or SAML provider reported, when it admitted). The code is presented without `client_id`, and its refresh token is set in the HttpOnly refresh cookie; a code presented with a `client_id` is invalid_grant. The code of a tenant switch's step-up or of a fresh reauthentication (below) opens no session: it is presented with the refresh token of the session that asked for it (its cookie, or `refresh_token`), and the answer is that session's tokens for the requested tenant (for a reauthentication, its own tenant), with the same `sub`, `sid` and `auth_time`; `amr` adds the methods just proven, and `reauth_time` is the instant of the last proof. - client_credentials: Application authentication (RFC 6749 Section 4.4) - refresh_token: Token refresh and tenant switch (RFC 6749 Section 6) - urn:ietf:params:oauth:grant-type:token-exchange: Impersonation (RFC 8693) Any other `grant_type`, `password` included, is answered `unsupported_grant_type`. **A person's session:** its refresh token is set in the HttpOnly refresh cookie and `refresh_token` is null in the body. It is presented without `client_id`: a person's refresh token presented with any `client_id` is invalid_grant. **One identity, several tenants:** a person is one identity holding a membership in each tenant they belong to, and every human token's `sub` is the identity id; `tenantId` is the membership in use. - A `refresh_token` grant carrying the `tenant_id` of another ACTIVE membership switches to it: a new access and refresh token for the target tenant, the same `sub`, the presented refresh token rotated. A refused switch is `invalid_grant` and leaves the presented refresh token usable for its own tenant. - A switch is decided on the evidence the session was authenticated with, against the target tenant's authentication posture. Evidence that satisfies it switches with no prompt, and switching back to a tenant entered earlier needs no new proof. Evidence that does not satisfy it is answered `403 insufficient_authorization` with an `auth_session` (draft-ietf-oauth-first-party-apps): nothing is issued or rotated, and the presented refresh token stays usable. The client continues at `POST /api/v3/auth/authorize-challenge` with that `auth_session`, a new S256 `code_challenge` and no `action`; only proofs of the session's own identity are accepted there, and a tenant that admits its members through an identity provider only is reached through that provider. The step ends in an authorization code redeemed as described above. - Every refresh and switch is minted from the target tenant's own facts, read from the authentication backend at that moment. In a tenant whose single sign-on is enforced, a membership linked to an identity provider is reached only by a session authenticated through that provider. - A session whose record does not state how it was opened (an authorization code, an emergency access or a federated sign-in) never refreshes or switches: the `refresh_token` grant answers it as a session past its absolute lifetime (invalid_grant, \"Refresh token is no longer valid. Please re-authenticate.\"), and the session ends, with every access token it issued. The person signs in again at POST /api/v3/auth/authorize-challenge. - A `refresh_token` grant carrying `max_age` (a non-negative integer of seconds, without a switch to another tenant) asks for a recent proof of the person. When the session's most recent authentication for its tenant is older than `max_age`, the answer is `403 insufficient_authorization` with an `auth_session`: nothing is issued or rotated, and the presented refresh token stays usable. The client continues the fresh reauthentication at `POST /api/v3/auth/authorize-challenge` with that `auth_session`, a new S256 `code_challenge` and no `action`. It re-proves the authority that admits the tenant, on its own proofs only: a passkey, a password and a TOTP code where the session was admitted with them, or the tenant's identity provider. The authorization code it ends in is redeemed with `grant_type=authorization_code`, the `code_verifier` and the session's refresh token: the same session is rotated and its tokens carry a new `reauth_time`. A session that holds no such proof (a password alone) receives `invalid_grant` and renews its proof by signing in again. With a recent enough proof the grant is an ordinary refresh. `max_age` on the refresh grant departs from RFC 6749, which defines no such parameter there: the refresh token is the only credential bound to the session that the client presents, so it is where the request for a fresh proof is made, as draft-ietf-oauth-first-party-apps allows a refresh to be answered with `insufficient_authorization`. **Security:** - Rate limited, and also operator-tunable: `auth.rate-limit.login-attempts-per-minute` and `auth.rate-limit.requests-per-minute` are platform settings this service reloads live. The shipped defaults are 10 attempts/min for the client_credentials grant and 30/min for the other grants; a deployment may have changed either - Tokens are JWTs signed with RS256 (RSA-3072) **Token Claims:** - HUMAN tokens: audience=ankasecure-admin, includes loginId (email) - APPLICATION tokens: audience=ankasecure-core, includes kp/kpv (key permissions) All tokens include: sub, iss, aud, exp, iat, jti, tenantId, scopes, userType. Human session tokens also carry `auth_method`: `pwd` for a password session, `fed:{idpId}` for a session established through an identity provider; `sid`, `auth_time` (the original sign-in, which never moves), `amr`, and `reauth_time`: the most recent proof of identity the session holds for the token's tenant, in epoch seconds. A sign-in proven by local or directory authenticators sets it to `auth_time`; a sign-in through an OIDC or SAML provider sets it to the instant the provider stated it authenticated the person (`auth_time` of its ID token, `AuthnInstant` of its assertion), never the instant of the callback, and omits it when the provider stated none. The session's `auth_time` stays the sign-in instant either way. A fresh reauthentication advances `reauth_time`, a plain refresh never does. **Impersonation tokens (token exchange, RFC 8693):** `act` names the operator (`sub`, `tenant_id`, `roles`, `username`) and `act.sid`, the operator's session the `subject_token` belongs to; `reauth_time` is the subject token's, unchanged; `impersonation` is `true` and the outer `roles` is the tenant role mirrored from the operator's platform role. No refresh token is issued. The token lives at most 900 seconds, never past the consent grant it rides or the absolute expiry of the operator's session, and the end of that session (logout, revocation) revokes it. `sub` is the operator's own identity id. **Administrative workloads (DPoP-bound tokens, RFC 9449):** a `client_credentials` request that carries a `DPoP` header is an administrative workload's. `client_id` is the workload id, and the workload authenticates with a `client_assertion` only — signed by a key registered on it (`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`, single-use) or minted for it by a trusted external issuer (`urn:ankatech:params:oauth:client-assertion-type:federated-jwt`). The `DPoP` header carries exactly one proof (`typ` `dpop+jwt`, alg ES256, ES384, PS256 or RS256, a public `jwk`, `htm` `POST`, `htu` the public token endpoint URL published in the authorization server metadata, `iat` within the last 60 seconds, a fresh `jti`). - The answer is `{\"access_token\", \"token_type\": \"DPoP\", \"expires_in\": 300}` with `Cache-Control: no-store` and no refresh token. The token (`typ` `at+jwt`) is for the administrative API only (`aud` `ankasecure-admin`), names the workload as `sub` and `client_id`, carries the workload's literal `scopes` and is bound to the proof key (`cnf.jkt`): every request with it carries `Authorization: DPoP` and a new proof. - A proof that is missing, repeated, malformed or stale is `400 invalid_dpop_proof`; no credential is examined. Every credential refusal is the same `401 invalid_client`. - The authorization server metadata (`GET /api/v3/auth/.well-known/oauth-authorization-server`) lists the proof algorithms in `dpop_signing_alg_values_supported`. - Without a `DPoP` header the grant authenticates a cryptographic actor and answers a Bearer token; a workload credential never yields a Bearer token.
      Parameters:
      grantType - OAuth 2.0 grant type per RFC 6749. Determines which authentication flow to use. Supported values: - authorization_code: Redeems the authorization code a sign-in at the authorization challenge endpoint ended in, with its PKCE code_verifier (RFC 6749 Section 4.1.3, RFC 7636) - client_credentials: Application authentication with client_id/client_secret (RFC 6749 Section 4.4) - refresh_token: Token refresh using refresh token, optionally switching tenant (RFC 6749 Section 6) - urn:ietf:params:oauth:grant-type:token-exchange: Token exchange for impersonation (RFC 8693) (required)
      dpoP - A DPoP proof (RFC 9449 §4), JWS compact serialization. Sent by an administrative workload with grant_type=client_credentials to obtain a DPoP-bound token; exactly one such header. Absent on every other request. (optional)
      tenantId - Tenant UUID. - refresh_token: OPTIONAL. Another ACTIVE membership of the same identity to switch to; absent or equal to the session's tenant, the session refreshes its own tenant. (optional)
      clientId - grant_type=client_credentials: REQUIRED. The UUID of the cryptographic ACTOR or administrative workload that holds the credential and is authenticating. An APPLICATION groups actors, holds no credential and cannot authenticate, so its id is never presented here. A person's grants (authorization_code, refresh_token) send none. (optional)
      clientSecret - Application secret. REQUIRED when grant_type=client_credentials. The secret credential for the application, validated against the stored hash. Minimum 8 characters. This secret is generated when the application is created and should be stored securely (environment variables, secret manager). (optional)
      clientAssertionType - Which assertion profile the client_assertion follows. REQUIRED when client_assertion is present. Two values are admitted: - urn:ietf:params:oauth:client-assertion-type:jwt-bearer (RFC 7523 §2.2) — the actor signed the assertion itself, with a key registered for it here. - urn:ankatech:params:oauth:client-assertion-type:federated-jwt — an external issuer this deployment trusts minted the token for the workload, and an (issuer, subject) declaration binds it to the actor named by client_id. This declared value is the ONLY thing that selects between them. The token's own contents are never inspected to make that choice. An unrecognised value is a 400 invalid_request, not a credential failure: the client asked for a profile this server does not implement, which is a malformed request rather than a wrong credential. (optional)
      clientAssertion - The assertion, in JWS compact serialization. REQUIRED when grant_type=client_credentials and the actor authenticates with an assertion rather than a shared secret. Bounded at 16 KiB; a larger value is refused as a credential failure, indistinguishably from any other. Under jwt-bearer the actor signed it: iss and sub are both the actor UUID, aud is the audience this deployment returned when the key was registered, and jti is single-use. Under federated-jwt an external issuer signed it: iss is that issuer, sub is the workload subject bound to the actor, aud is the audience this deployment derived for the issuer, and jti is optional. (optional)
      exchangeContext - OPTIONAL Exchange Context UUID for grant_type=client_credentials when the client_id is a Cryptographic Actor. The issued JWT carries the supplied value in the exchangeContextId claim, binding the token to operations conducted under that Exchange Context. Omit this parameter for Actors that operate without a specific Exchange Context (internal operations) — the emitted JWT then carries null exchangeContextId and the cryptographic service will match grants that also have null exchange_context_id. (optional)
      refreshToken - Opaque refresh token for grant_type=refresh_token. A person's session presents it in the httpOnly refresh cookie, or here, without a client_id. If both are present, this parameter takes precedence. (optional)
      subjectToken - JWT access token to exchange. REQUIRED when grant_type=urn:ietf:params:oauth:grant-type:token-exchange. This is the platform admin's JWT token that will be exchanged for a tenant-scoped token. The token must have platform-level privileges to perform impersonation. Format: JWT with RS256 signature. (optional)
      subjectTokenType - Type of subject_token per RFC 8693. OPTIONAL for token exchange. Standard value: urn:ietf:params:oauth:token-type:access_token If omitted, defaults to access_token type. (optional)
      requestedTokenType - Type of requested token per RFC 8693. OPTIONAL for token exchange. Standard value: urn:ietf:params:oauth:token-type:access_token If omitted, defaults to access_token type. (optional)
      resource - Target tenant URI for impersonation. REQUIRED when grant_type=urn:ietf:params:oauth:grant-type:token-exchange. Format: urn:ankatech:tenant:<tenant-uuid> Example: urn:ankatech:tenant:00000000-0000-0000-0000-000000000003 This identifies which tenant the impersonation token should target. The platform admin will receive a token with tenant-scoped privileges. (optional)
      scope - Space-delimited list of requested scopes. OPTIONAL for all grant types. Accepted and ignored: the issued token carries the scopes its subject's role assignments grant, whatever this parameter requests. A value here neither narrows nor widens them, and is never an error. (optional)
      code - The authorization code of a completed sign-in at the authorization challenge endpoint. REQUIRED when grant_type=authorization_code. Valid for 60 seconds and consumed by its first presentation, whatever the outcome: a second presentation, a wrong code_verifier or an expired code is invalid_grant. (optional)
      codeVerifier - The PKCE code_verifier whose S256 challenge started the sign-in (RFC 7636 Section 4.5). REQUIRED when grant_type=authorization_code. 43 to 128 characters of [A-Z a-z 0-9 - . _ ~]. (optional)
      maxAge - The oldest proof of identity, in seconds, the refreshed session may rest on (OIDC Core 1.0 max_age). OPTIONAL, and accepted only when grant_type=refresh_token without a switch to another tenant. A non-negative integer. When the session's most recent authentication for its tenant is older, the refresh is answered 403 insufficient_authorization with an auth_session that continues a fresh reauthentication at the authorization challenge endpoint; nothing is rotated. (optional)
      rememberMe - Remember this sign-in. OPTIONAL when grant_type=authorization_code. Values: - true: the refresh cookie is persistent, with a Max-Age equal to the seconds left to the session's absolute expiry, and the longer Remember Me inactivity window applies (auth.session.remember-me.inactivity-timeout-minutes). Ignored while auth.session.remember-me.enabled is false. - false or omitted: the refresh cookie is a session cookie and the standard inactivity window applies (auth.session.inactivity-timeout-minutes). Remember Me never extends the session's absolute expiry (auth.session.absolute-lifetime-minutes). Only applies to the authorization_code grant; refreshes keep the session's choice. (optional, default to false)
      Returns:
      TokenResponse
      Throws:
      ApiException - If fail to call the API, e.g. server error or cannot deserialize the response body

    • createTokenWithHttpInfo

      public ApiResponse<TokenResponse> createTokenWithHttpInfo(@Nonnull String grantType, @Nullable String dpoP, @Nullable UUID tenantId, @Nullable String clientId, @Nullable String clientSecret, @Nullable String clientAssertionType, @Nullable String clientAssertion, @Nullable UUID exchangeContext, @Nullable String refreshToken, @Nullable String subjectToken, @Nullable URI subjectTokenType, @Nullable URI requestedTokenType, @Nullable URI resource, @Nullable String scope, @Nullable String code, @Nullable String codeVerifier, @Nullable String maxAge, @Nullable String rememberMe) throws ApiException
      OAuth 2.0 token endpoint (RFC 6749/8693) OAuth 2.0 token endpoint supporting five grant types. **Request Format:** application/x-www-form-urlencoded (OAuth 2.0 standard) **Supported Grant Types:** - authorization_code: Redeems the authorization code a sign-in at POST /api/v3/auth/authorize-challenge ended in, with its PKCE code_verifier (RFC 6749 Section 4.1.3, RFC 7636 Section 4.5). The code is valid for 60 seconds and is consumed by its first presentation; a second presentation, a wrong code_verifier or an expired code is invalid_grant. The answer is the session of the tenant the sign-in admitted; `amr` names the methods of the authority that admitted the membership (`user` and `hwk` or `swk` for a passkey; the methods the OIDC or SAML provider reported, when it admitted). The code is presented without `client_id`, and its refresh token is set in the HttpOnly refresh cookie; a code presented with a `client_id` is invalid_grant. The code of a tenant switch's step-up or of a fresh reauthentication (below) opens no session: it is presented with the refresh token of the session that asked for it (its cookie, or `refresh_token`), and the answer is that session's tokens for the requested tenant (for a reauthentication, its own tenant), with the same `sub`, `sid` and `auth_time`; `amr` adds the methods just proven, and `reauth_time` is the instant of the last proof. - client_credentials: Application authentication (RFC 6749 Section 4.4) - refresh_token: Token refresh and tenant switch (RFC 6749 Section 6) - urn:ietf:params:oauth:grant-type:token-exchange: Impersonation (RFC 8693) Any other `grant_type`, `password` included, is answered `unsupported_grant_type`. **A person's session:** its refresh token is set in the HttpOnly refresh cookie and `refresh_token` is null in the body. It is presented without `client_id`: a person's refresh token presented with any `client_id` is invalid_grant. **One identity, several tenants:** a person is one identity holding a membership in each tenant they belong to, and every human token's `sub` is the identity id; `tenantId` is the membership in use. - A `refresh_token` grant carrying the `tenant_id` of another ACTIVE membership switches to it: a new access and refresh token for the target tenant, the same `sub`, the presented refresh token rotated. A refused switch is `invalid_grant` and leaves the presented refresh token usable for its own tenant. - A switch is decided on the evidence the session was authenticated with, against the target tenant's authentication posture. Evidence that satisfies it switches with no prompt, and switching back to a tenant entered earlier needs no new proof. Evidence that does not satisfy it is answered `403 insufficient_authorization` with an `auth_session` (draft-ietf-oauth-first-party-apps): nothing is issued or rotated, and the presented refresh token stays usable. The client continues at `POST /api/v3/auth/authorize-challenge` with that `auth_session`, a new S256 `code_challenge` and no `action`; only proofs of the session's own identity are accepted there, and a tenant that admits its members through an identity provider only is reached through that provider. The step ends in an authorization code redeemed as described above. - Every refresh and switch is minted from the target tenant's own facts, read from the authentication backend at that moment. In a tenant whose single sign-on is enforced, a membership linked to an identity provider is reached only by a session authenticated through that provider. - A session whose record does not state how it was opened (an authorization code, an emergency access or a federated sign-in) never refreshes or switches: the `refresh_token` grant answers it as a session past its absolute lifetime (invalid_grant, \"Refresh token is no longer valid. Please re-authenticate.\"), and the session ends, with every access token it issued. The person signs in again at POST /api/v3/auth/authorize-challenge. - A `refresh_token` grant carrying `max_age` (a non-negative integer of seconds, without a switch to another tenant) asks for a recent proof of the person. When the session's most recent authentication for its tenant is older than `max_age`, the answer is `403 insufficient_authorization` with an `auth_session`: nothing is issued or rotated, and the presented refresh token stays usable. The client continues the fresh reauthentication at `POST /api/v3/auth/authorize-challenge` with that `auth_session`, a new S256 `code_challenge` and no `action`. It re-proves the authority that admits the tenant, on its own proofs only: a passkey, a password and a TOTP code where the session was admitted with them, or the tenant's identity provider. The authorization code it ends in is redeemed with `grant_type=authorization_code`, the `code_verifier` and the session's refresh token: the same session is rotated and its tokens carry a new `reauth_time`. A session that holds no such proof (a password alone) receives `invalid_grant` and renews its proof by signing in again. With a recent enough proof the grant is an ordinary refresh. `max_age` on the refresh grant departs from RFC 6749, which defines no such parameter there: the refresh token is the only credential bound to the session that the client presents, so it is where the request for a fresh proof is made, as draft-ietf-oauth-first-party-apps allows a refresh to be answered with `insufficient_authorization`. **Security:** - Rate limited, and also operator-tunable: `auth.rate-limit.login-attempts-per-minute` and `auth.rate-limit.requests-per-minute` are platform settings this service reloads live. The shipped defaults are 10 attempts/min for the client_credentials grant and 30/min for the other grants; a deployment may have changed either - Tokens are JWTs signed with RS256 (RSA-3072) **Token Claims:** - HUMAN tokens: audience=ankasecure-admin, includes loginId (email) - APPLICATION tokens: audience=ankasecure-core, includes kp/kpv (key permissions) All tokens include: sub, iss, aud, exp, iat, jti, tenantId, scopes, userType. Human session tokens also carry `auth_method`: `pwd` for a password session, `fed:{idpId}` for a session established through an identity provider; `sid`, `auth_time` (the original sign-in, which never moves), `amr`, and `reauth_time`: the most recent proof of identity the session holds for the token's tenant, in epoch seconds. A sign-in proven by local or directory authenticators sets it to `auth_time`; a sign-in through an OIDC or SAML provider sets it to the instant the provider stated it authenticated the person (`auth_time` of its ID token, `AuthnInstant` of its assertion), never the instant of the callback, and omits it when the provider stated none. The session's `auth_time` stays the sign-in instant either way. A fresh reauthentication advances `reauth_time`, a plain refresh never does. **Impersonation tokens (token exchange, RFC 8693):** `act` names the operator (`sub`, `tenant_id`, `roles`, `username`) and `act.sid`, the operator's session the `subject_token` belongs to; `reauth_time` is the subject token's, unchanged; `impersonation` is `true` and the outer `roles` is the tenant role mirrored from the operator's platform role. No refresh token is issued. The token lives at most 900 seconds, never past the consent grant it rides or the absolute expiry of the operator's session, and the end of that session (logout, revocation) revokes it. `sub` is the operator's own identity id. **Administrative workloads (DPoP-bound tokens, RFC 9449):** a `client_credentials` request that carries a `DPoP` header is an administrative workload's. `client_id` is the workload id, and the workload authenticates with a `client_assertion` only — signed by a key registered on it (`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`, single-use) or minted for it by a trusted external issuer (`urn:ankatech:params:oauth:client-assertion-type:federated-jwt`). The `DPoP` header carries exactly one proof (`typ` `dpop+jwt`, alg ES256, ES384, PS256 or RS256, a public `jwk`, `htm` `POST`, `htu` the public token endpoint URL published in the authorization server metadata, `iat` within the last 60 seconds, a fresh `jti`). - The answer is `{\"access_token\", \"token_type\": \"DPoP\", \"expires_in\": 300}` with `Cache-Control: no-store` and no refresh token. The token (`typ` `at+jwt`) is for the administrative API only (`aud` `ankasecure-admin`), names the workload as `sub` and `client_id`, carries the workload's literal `scopes` and is bound to the proof key (`cnf.jkt`): every request with it carries `Authorization: DPoP` and a new proof. - A proof that is missing, repeated, malformed or stale is `400 invalid_dpop_proof`; no credential is examined. Every credential refusal is the same `401 invalid_client`. - The authorization server metadata (`GET /api/v3/auth/.well-known/oauth-authorization-server`) lists the proof algorithms in `dpop_signing_alg_values_supported`. - Without a `DPoP` header the grant authenticates a cryptographic actor and answers a Bearer token; a workload credential never yields a Bearer token.
      Parameters:
      grantType - OAuth 2.0 grant type per RFC 6749. Determines which authentication flow to use. Supported values: - authorization_code: Redeems the authorization code a sign-in at the authorization challenge endpoint ended in, with its PKCE code_verifier (RFC 6749 Section 4.1.3, RFC 7636) - client_credentials: Application authentication with client_id/client_secret (RFC 6749 Section 4.4) - refresh_token: Token refresh using refresh token, optionally switching tenant (RFC 6749 Section 6) - urn:ietf:params:oauth:grant-type:token-exchange: Token exchange for impersonation (RFC 8693) (required)
      dpoP - A DPoP proof (RFC 9449 §4), JWS compact serialization. Sent by an administrative workload with grant_type=client_credentials to obtain a DPoP-bound token; exactly one such header. Absent on every other request. (optional)
      tenantId - Tenant UUID. - refresh_token: OPTIONAL. Another ACTIVE membership of the same identity to switch to; absent or equal to the session's tenant, the session refreshes its own tenant. (optional)
      clientId - grant_type=client_credentials: REQUIRED. The UUID of the cryptographic ACTOR or administrative workload that holds the credential and is authenticating. An APPLICATION groups actors, holds no credential and cannot authenticate, so its id is never presented here. A person's grants (authorization_code, refresh_token) send none. (optional)
      clientSecret - Application secret. REQUIRED when grant_type=client_credentials. The secret credential for the application, validated against the stored hash. Minimum 8 characters. This secret is generated when the application is created and should be stored securely (environment variables, secret manager). (optional)
      clientAssertionType - Which assertion profile the client_assertion follows. REQUIRED when client_assertion is present. Two values are admitted: - urn:ietf:params:oauth:client-assertion-type:jwt-bearer (RFC 7523 §2.2) — the actor signed the assertion itself, with a key registered for it here. - urn:ankatech:params:oauth:client-assertion-type:federated-jwt — an external issuer this deployment trusts minted the token for the workload, and an (issuer, subject) declaration binds it to the actor named by client_id. This declared value is the ONLY thing that selects between them. The token's own contents are never inspected to make that choice. An unrecognised value is a 400 invalid_request, not a credential failure: the client asked for a profile this server does not implement, which is a malformed request rather than a wrong credential. (optional)
      clientAssertion - The assertion, in JWS compact serialization. REQUIRED when grant_type=client_credentials and the actor authenticates with an assertion rather than a shared secret. Bounded at 16 KiB; a larger value is refused as a credential failure, indistinguishably from any other. Under jwt-bearer the actor signed it: iss and sub are both the actor UUID, aud is the audience this deployment returned when the key was registered, and jti is single-use. Under federated-jwt an external issuer signed it: iss is that issuer, sub is the workload subject bound to the actor, aud is the audience this deployment derived for the issuer, and jti is optional. (optional)
      exchangeContext - OPTIONAL Exchange Context UUID for grant_type=client_credentials when the client_id is a Cryptographic Actor. The issued JWT carries the supplied value in the exchangeContextId claim, binding the token to operations conducted under that Exchange Context. Omit this parameter for Actors that operate without a specific Exchange Context (internal operations) — the emitted JWT then carries null exchangeContextId and the cryptographic service will match grants that also have null exchange_context_id. (optional)
      refreshToken - Opaque refresh token for grant_type=refresh_token. A person's session presents it in the httpOnly refresh cookie, or here, without a client_id. If both are present, this parameter takes precedence. (optional)
      subjectToken - JWT access token to exchange. REQUIRED when grant_type=urn:ietf:params:oauth:grant-type:token-exchange. This is the platform admin's JWT token that will be exchanged for a tenant-scoped token. The token must have platform-level privileges to perform impersonation. Format: JWT with RS256 signature. (optional)
      subjectTokenType - Type of subject_token per RFC 8693. OPTIONAL for token exchange. Standard value: urn:ietf:params:oauth:token-type:access_token If omitted, defaults to access_token type. (optional)
      requestedTokenType - Type of requested token per RFC 8693. OPTIONAL for token exchange. Standard value: urn:ietf:params:oauth:token-type:access_token If omitted, defaults to access_token type. (optional)
      resource - Target tenant URI for impersonation. REQUIRED when grant_type=urn:ietf:params:oauth:grant-type:token-exchange. Format: urn:ankatech:tenant:<tenant-uuid> Example: urn:ankatech:tenant:00000000-0000-0000-0000-000000000003 This identifies which tenant the impersonation token should target. The platform admin will receive a token with tenant-scoped privileges. (optional)
      scope - Space-delimited list of requested scopes. OPTIONAL for all grant types. Accepted and ignored: the issued token carries the scopes its subject's role assignments grant, whatever this parameter requests. A value here neither narrows nor widens them, and is never an error. (optional)
      code - The authorization code of a completed sign-in at the authorization challenge endpoint. REQUIRED when grant_type=authorization_code. Valid for 60 seconds and consumed by its first presentation, whatever the outcome: a second presentation, a wrong code_verifier or an expired code is invalid_grant. (optional)
      codeVerifier - The PKCE code_verifier whose S256 challenge started the sign-in (RFC 7636 Section 4.5). REQUIRED when grant_type=authorization_code. 43 to 128 characters of [A-Z a-z 0-9 - . _ ~]. (optional)
      maxAge - The oldest proof of identity, in seconds, the refreshed session may rest on (OIDC Core 1.0 max_age). OPTIONAL, and accepted only when grant_type=refresh_token without a switch to another tenant. A non-negative integer. When the session's most recent authentication for its tenant is older, the refresh is answered 403 insufficient_authorization with an auth_session that continues a fresh reauthentication at the authorization challenge endpoint; nothing is rotated. (optional)
      rememberMe - Remember this sign-in. OPTIONAL when grant_type=authorization_code. Values: - true: the refresh cookie is persistent, with a Max-Age equal to the seconds left to the session's absolute expiry, and the longer Remember Me inactivity window applies (auth.session.remember-me.inactivity-timeout-minutes). Ignored while auth.session.remember-me.enabled is false. - false or omitted: the refresh cookie is a session cookie and the standard inactivity window applies (auth.session.inactivity-timeout-minutes). Remember Me never extends the session's absolute expiry (auth.session.absolute-lifetime-minutes). Only applies to the authorization_code grant; refreshes keep the session's choice. (optional, default to false)
      Returns:
      ApiResponse<TokenResponse>
      Throws:
      ApiException - If fail to call the API, e.g. server error or cannot deserialize the response body

    • createTokenAsync

      public okhttp3.Call createTokenAsync(@Nonnull String grantType, @Nullable String dpoP, @Nullable UUID tenantId, @Nullable String clientId, @Nullable String clientSecret, @Nullable String clientAssertionType, @Nullable String clientAssertion, @Nullable UUID exchangeContext, @Nullable String refreshToken, @Nullable String subjectToken, @Nullable URI subjectTokenType, @Nullable URI requestedTokenType, @Nullable URI resource, @Nullable String scope, @Nullable String code, @Nullable String codeVerifier, @Nullable String maxAge, @Nullable String rememberMe, ApiCallback<TokenResponse> _callback) throws ApiException
      OAuth 2.0 token endpoint (RFC 6749/8693) (asynchronously) OAuth 2.0 token endpoint supporting five grant types. **Request Format:** application/x-www-form-urlencoded (OAuth 2.0 standard) **Supported Grant Types:** - authorization_code: Redeems the authorization code a sign-in at POST /api/v3/auth/authorize-challenge ended in, with its PKCE code_verifier (RFC 6749 Section 4.1.3, RFC 7636 Section 4.5). The code is valid for 60 seconds and is consumed by its first presentation; a second presentation, a wrong code_verifier or an expired code is invalid_grant. The answer is the session of the tenant the sign-in admitted; `amr` names the methods of the authority that admitted the membership (`user` and `hwk` or `swk` for a passkey; the methods the OIDC or SAML provider reported, when it admitted). The code is presented without `client_id`, and its refresh token is set in the HttpOnly refresh cookie; a code presented with a `client_id` is invalid_grant. The code of a tenant switch's step-up or of a fresh reauthentication (below) opens no session: it is presented with the refresh token of the session that asked for it (its cookie, or `refresh_token`), and the answer is that session's tokens for the requested tenant (for a reauthentication, its own tenant), with the same `sub`, `sid` and `auth_time`; `amr` adds the methods just proven, and `reauth_time` is the instant of the last proof. - client_credentials: Application authentication (RFC 6749 Section 4.4) - refresh_token: Token refresh and tenant switch (RFC 6749 Section 6) - urn:ietf:params:oauth:grant-type:token-exchange: Impersonation (RFC 8693) Any other `grant_type`, `password` included, is answered `unsupported_grant_type`. **A person's session:** its refresh token is set in the HttpOnly refresh cookie and `refresh_token` is null in the body. It is presented without `client_id`: a person's refresh token presented with any `client_id` is invalid_grant. **One identity, several tenants:** a person is one identity holding a membership in each tenant they belong to, and every human token's `sub` is the identity id; `tenantId` is the membership in use. - A `refresh_token` grant carrying the `tenant_id` of another ACTIVE membership switches to it: a new access and refresh token for the target tenant, the same `sub`, the presented refresh token rotated. A refused switch is `invalid_grant` and leaves the presented refresh token usable for its own tenant. - A switch is decided on the evidence the session was authenticated with, against the target tenant's authentication posture. Evidence that satisfies it switches with no prompt, and switching back to a tenant entered earlier needs no new proof. Evidence that does not satisfy it is answered `403 insufficient_authorization` with an `auth_session` (draft-ietf-oauth-first-party-apps): nothing is issued or rotated, and the presented refresh token stays usable. The client continues at `POST /api/v3/auth/authorize-challenge` with that `auth_session`, a new S256 `code_challenge` and no `action`; only proofs of the session's own identity are accepted there, and a tenant that admits its members through an identity provider only is reached through that provider. The step ends in an authorization code redeemed as described above. - Every refresh and switch is minted from the target tenant's own facts, read from the authentication backend at that moment. In a tenant whose single sign-on is enforced, a membership linked to an identity provider is reached only by a session authenticated through that provider. - A session whose record does not state how it was opened (an authorization code, an emergency access or a federated sign-in) never refreshes or switches: the `refresh_token` grant answers it as a session past its absolute lifetime (invalid_grant, \"Refresh token is no longer valid. Please re-authenticate.\"), and the session ends, with every access token it issued. The person signs in again at POST /api/v3/auth/authorize-challenge. - A `refresh_token` grant carrying `max_age` (a non-negative integer of seconds, without a switch to another tenant) asks for a recent proof of the person. When the session's most recent authentication for its tenant is older than `max_age`, the answer is `403 insufficient_authorization` with an `auth_session`: nothing is issued or rotated, and the presented refresh token stays usable. The client continues the fresh reauthentication at `POST /api/v3/auth/authorize-challenge` with that `auth_session`, a new S256 `code_challenge` and no `action`. It re-proves the authority that admits the tenant, on its own proofs only: a passkey, a password and a TOTP code where the session was admitted with them, or the tenant's identity provider. The authorization code it ends in is redeemed with `grant_type=authorization_code`, the `code_verifier` and the session's refresh token: the same session is rotated and its tokens carry a new `reauth_time`. A session that holds no such proof (a password alone) receives `invalid_grant` and renews its proof by signing in again. With a recent enough proof the grant is an ordinary refresh. `max_age` on the refresh grant departs from RFC 6749, which defines no such parameter there: the refresh token is the only credential bound to the session that the client presents, so it is where the request for a fresh proof is made, as draft-ietf-oauth-first-party-apps allows a refresh to be answered with `insufficient_authorization`. **Security:** - Rate limited, and also operator-tunable: `auth.rate-limit.login-attempts-per-minute` and `auth.rate-limit.requests-per-minute` are platform settings this service reloads live. The shipped defaults are 10 attempts/min for the client_credentials grant and 30/min for the other grants; a deployment may have changed either - Tokens are JWTs signed with RS256 (RSA-3072) **Token Claims:** - HUMAN tokens: audience=ankasecure-admin, includes loginId (email) - APPLICATION tokens: audience=ankasecure-core, includes kp/kpv (key permissions) All tokens include: sub, iss, aud, exp, iat, jti, tenantId, scopes, userType. Human session tokens also carry `auth_method`: `pwd` for a password session, `fed:{idpId}` for a session established through an identity provider; `sid`, `auth_time` (the original sign-in, which never moves), `amr`, and `reauth_time`: the most recent proof of identity the session holds for the token's tenant, in epoch seconds. A sign-in proven by local or directory authenticators sets it to `auth_time`; a sign-in through an OIDC or SAML provider sets it to the instant the provider stated it authenticated the person (`auth_time` of its ID token, `AuthnInstant` of its assertion), never the instant of the callback, and omits it when the provider stated none. The session's `auth_time` stays the sign-in instant either way. A fresh reauthentication advances `reauth_time`, a plain refresh never does. **Impersonation tokens (token exchange, RFC 8693):** `act` names the operator (`sub`, `tenant_id`, `roles`, `username`) and `act.sid`, the operator's session the `subject_token` belongs to; `reauth_time` is the subject token's, unchanged; `impersonation` is `true` and the outer `roles` is the tenant role mirrored from the operator's platform role. No refresh token is issued. The token lives at most 900 seconds, never past the consent grant it rides or the absolute expiry of the operator's session, and the end of that session (logout, revocation) revokes it. `sub` is the operator's own identity id. **Administrative workloads (DPoP-bound tokens, RFC 9449):** a `client_credentials` request that carries a `DPoP` header is an administrative workload's. `client_id` is the workload id, and the workload authenticates with a `client_assertion` only — signed by a key registered on it (`urn:ietf:params:oauth:client-assertion-type:jwt-bearer`, single-use) or minted for it by a trusted external issuer (`urn:ankatech:params:oauth:client-assertion-type:federated-jwt`). The `DPoP` header carries exactly one proof (`typ` `dpop+jwt`, alg ES256, ES384, PS256 or RS256, a public `jwk`, `htm` `POST`, `htu` the public token endpoint URL published in the authorization server metadata, `iat` within the last 60 seconds, a fresh `jti`). - The answer is `{\"access_token\", \"token_type\": \"DPoP\", \"expires_in\": 300}` with `Cache-Control: no-store` and no refresh token. The token (`typ` `at+jwt`) is for the administrative API only (`aud` `ankasecure-admin`), names the workload as `sub` and `client_id`, carries the workload's literal `scopes` and is bound to the proof key (`cnf.jkt`): every request with it carries `Authorization: DPoP` and a new proof. - A proof that is missing, repeated, malformed or stale is `400 invalid_dpop_proof`; no credential is examined. Every credential refusal is the same `401 invalid_client`. - The authorization server metadata (`GET /api/v3/auth/.well-known/oauth-authorization-server`) lists the proof algorithms in `dpop_signing_alg_values_supported`. - Without a `DPoP` header the grant authenticates a cryptographic actor and answers a Bearer token; a workload credential never yields a Bearer token.
      Parameters:
      grantType - OAuth 2.0 grant type per RFC 6749. Determines which authentication flow to use. Supported values: - authorization_code: Redeems the authorization code a sign-in at the authorization challenge endpoint ended in, with its PKCE code_verifier (RFC 6749 Section 4.1.3, RFC 7636) - client_credentials: Application authentication with client_id/client_secret (RFC 6749 Section 4.4) - refresh_token: Token refresh using refresh token, optionally switching tenant (RFC 6749 Section 6) - urn:ietf:params:oauth:grant-type:token-exchange: Token exchange for impersonation (RFC 8693) (required)
      dpoP - A DPoP proof (RFC 9449 §4), JWS compact serialization. Sent by an administrative workload with grant_type=client_credentials to obtain a DPoP-bound token; exactly one such header. Absent on every other request. (optional)
      tenantId - Tenant UUID. - refresh_token: OPTIONAL. Another ACTIVE membership of the same identity to switch to; absent or equal to the session's tenant, the session refreshes its own tenant. (optional)
      clientId - grant_type=client_credentials: REQUIRED. The UUID of the cryptographic ACTOR or administrative workload that holds the credential and is authenticating. An APPLICATION groups actors, holds no credential and cannot authenticate, so its id is never presented here. A person's grants (authorization_code, refresh_token) send none. (optional)
      clientSecret - Application secret. REQUIRED when grant_type=client_credentials. The secret credential for the application, validated against the stored hash. Minimum 8 characters. This secret is generated when the application is created and should be stored securely (environment variables, secret manager). (optional)
      clientAssertionType - Which assertion profile the client_assertion follows. REQUIRED when client_assertion is present. Two values are admitted: - urn:ietf:params:oauth:client-assertion-type:jwt-bearer (RFC 7523 §2.2) — the actor signed the assertion itself, with a key registered for it here. - urn:ankatech:params:oauth:client-assertion-type:federated-jwt — an external issuer this deployment trusts minted the token for the workload, and an (issuer, subject) declaration binds it to the actor named by client_id. This declared value is the ONLY thing that selects between them. The token's own contents are never inspected to make that choice. An unrecognised value is a 400 invalid_request, not a credential failure: the client asked for a profile this server does not implement, which is a malformed request rather than a wrong credential. (optional)
      clientAssertion - The assertion, in JWS compact serialization. REQUIRED when grant_type=client_credentials and the actor authenticates with an assertion rather than a shared secret. Bounded at 16 KiB; a larger value is refused as a credential failure, indistinguishably from any other. Under jwt-bearer the actor signed it: iss and sub are both the actor UUID, aud is the audience this deployment returned when the key was registered, and jti is single-use. Under federated-jwt an external issuer signed it: iss is that issuer, sub is the workload subject bound to the actor, aud is the audience this deployment derived for the issuer, and jti is optional. (optional)
      exchangeContext - OPTIONAL Exchange Context UUID for grant_type=client_credentials when the client_id is a Cryptographic Actor. The issued JWT carries the supplied value in the exchangeContextId claim, binding the token to operations conducted under that Exchange Context. Omit this parameter for Actors that operate without a specific Exchange Context (internal operations) — the emitted JWT then carries null exchangeContextId and the cryptographic service will match grants that also have null exchange_context_id. (optional)
      refreshToken - Opaque refresh token for grant_type=refresh_token. A person's session presents it in the httpOnly refresh cookie, or here, without a client_id. If both are present, this parameter takes precedence. (optional)
      subjectToken - JWT access token to exchange. REQUIRED when grant_type=urn:ietf:params:oauth:grant-type:token-exchange. This is the platform admin's JWT token that will be exchanged for a tenant-scoped token. The token must have platform-level privileges to perform impersonation. Format: JWT with RS256 signature. (optional)
      subjectTokenType - Type of subject_token per RFC 8693. OPTIONAL for token exchange. Standard value: urn:ietf:params:oauth:token-type:access_token If omitted, defaults to access_token type. (optional)
      requestedTokenType - Type of requested token per RFC 8693. OPTIONAL for token exchange. Standard value: urn:ietf:params:oauth:token-type:access_token If omitted, defaults to access_token type. (optional)
      resource - Target tenant URI for impersonation. REQUIRED when grant_type=urn:ietf:params:oauth:grant-type:token-exchange. Format: urn:ankatech:tenant:<tenant-uuid> Example: urn:ankatech:tenant:00000000-0000-0000-0000-000000000003 This identifies which tenant the impersonation token should target. The platform admin will receive a token with tenant-scoped privileges. (optional)
      scope - Space-delimited list of requested scopes. OPTIONAL for all grant types. Accepted and ignored: the issued token carries the scopes its subject's role assignments grant, whatever this parameter requests. A value here neither narrows nor widens them, and is never an error. (optional)
      code - The authorization code of a completed sign-in at the authorization challenge endpoint. REQUIRED when grant_type=authorization_code. Valid for 60 seconds and consumed by its first presentation, whatever the outcome: a second presentation, a wrong code_verifier or an expired code is invalid_grant. (optional)
      codeVerifier - The PKCE code_verifier whose S256 challenge started the sign-in (RFC 7636 Section 4.5). REQUIRED when grant_type=authorization_code. 43 to 128 characters of [A-Z a-z 0-9 - . _ ~]. (optional)
      maxAge - The oldest proof of identity, in seconds, the refreshed session may rest on (OIDC Core 1.0 max_age). OPTIONAL, and accepted only when grant_type=refresh_token without a switch to another tenant. A non-negative integer. When the session's most recent authentication for its tenant is older, the refresh is answered 403 insufficient_authorization with an auth_session that continues a fresh reauthentication at the authorization challenge endpoint; nothing is rotated. (optional)
      rememberMe - Remember this sign-in. OPTIONAL when grant_type=authorization_code. Values: - true: the refresh cookie is persistent, with a Max-Age equal to the seconds left to the session's absolute expiry, and the longer Remember Me inactivity window applies (auth.session.remember-me.inactivity-timeout-minutes). Ignored while auth.session.remember-me.enabled is false. - false or omitted: the refresh cookie is a session cookie and the standard inactivity window applies (auth.session.inactivity-timeout-minutes). Remember Me never extends the session's absolute expiry (auth.session.absolute-lifetime-minutes). Only applies to the authorization_code grant; refreshes keep the session's choice. (optional, default to false)
      _callback - The callback to be executed when the API call finishes
      Returns:
      The request call
      Throws:
      ApiException - If fail to process the API call, e.g. serializing the request body object