API Reference
  1. AnkaSecure Auth API
  2. Token Management

OAuth 2.0 token endpoint (RFC 6749/8693)

post
https://staging.ankatech.co/api/v3/auth/token

OAuth 2.0 token endpoint supporting four grant types.

Request Format: application/x-www-form-urlencoded (OAuth 2.0 standard)

Supported Grant Types:

  • password: User authentication (RFC 6749 Section 4.3)
  • client_credentials: Application authentication (RFC 6749 Section 4.4)
  • refresh_token: Token refresh (RFC 6749 Section 6)
  • urn:ietf:params:oauth:grant-type:token-exchange: Impersonation (RFC 8693)

Security:

  • Rate limited: 10 attempts/min for password grant, 30/min for refresh
  • Account lockout: 5 failed attempts → 15 min lockout
  • 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

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Form Data

OAuth 2.0 token request with grant_type parameter

OAuth 2.0 token request supporting password, client_credentials, and refresh_token grant types.
Required fields depend on grant_type value.

string
length between 0 and 320

User email address. REQUIRED when grant_type=password.

This is the primary login identifier for human users in the AnkaSecure platform.
Must be a valid email format per RFC 5322 and not exceed 320 characters.

password
length between 8 and 2147483647

User password. REQUIRED when grant_type=password.

The password is validated against the stored PBKDF2 hash in the database.
Minimum 8 characters required (configurable by admin policies).

string
enum
required
length ≥ 1

OAuth 2.0 grant type per RFC 6749. Determines which authentication flow to use.

Supported values:

  • password: User authentication with username/password (RFC 6749 Section 4.3)
  • client_credentials: Application authentication with client_id/client_secret (RFC 6749 Section 4.4)
  • refresh_token: Token refresh using refresh token (RFC 6749 Section 6)
  • urn:ietf:params:oauth:grant-type:token-exchange: Token exchange for impersonation (RFC 8693)
Allowed:
uuid
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Tenant UUID. REQUIRED when grant_type=password.

Identifies which tenant the user belongs to for multi-tenant isolation.
Must be a valid UUID v4 format.

uuid
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Application UUID. REQUIRED when grant_type=client_credentials.

Identifies the application (non-human principal) requesting authentication.
This is the application's unique identifier created via Admin-API.
Must be a valid UUID v4 format.

password
length between 8 and 2147483647

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).

string

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 (PRD §181) — 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.

string

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.

uuid

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 Core API resolver will match grants that also
have null exchange_context_id.

uuid
^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Opaque refresh token UUID. OPTIONAL when grant_type=refresh_token.

Can be provided in request body OR via httpOnly cookie (AnkaSecure_Refresh_Token).
If both are present, body parameter takes precedence.
Token format: UUID v4 (36 characters) per RFC 9700 (opaque tokens).

string

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.

uri
enum

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.

Allowed:
uri
enum

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.

Allowed:
uri
^urn:ankatech:tenant:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Target tenant URI for impersonation. REQUIRED when grant_type=urn:ietf:params:oauth:grant-type:token-exchange.

Format: urn:ankatech:tenant:
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.

string

Space-delimited list of requested scopes. OPTIONAL for all grant types.

NOTE: Currently not fully implemented. Scopes are automatically derived from
user/application role assignments in the Admin-API.

Future enhancement will support dynamic scope requests for token exchange.
Example: "admin.tenant.user.read admin.tenant.user.update"

string
Defaults to false

Extend refresh token lifetime. OPTIONAL when grant_type=password.

Values:

  • true: Refresh token valid for the configured remember-me lifetime (default 7 days, operator-configurable 1-90 days)
  • false or omitted: Refresh token valid for the standard session (jwt.refreshExpirationSeconds)

Only applies to password grant. Ignored for client_credentials and refresh_token grants.

Security consideration: Long-lived sessions increase attack surface. Use only when
appropriate for the use case (e.g., mobile apps, trusted devices).

Headers
string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Updated 11 days ago

Did this page help you?
Language
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
application/problem+json

Updated 11 days ago

Did this page help you?