> ## Documentation Index > Fetch the complete documentation index at: https://team.k0labs.com/llms.txt > Use this file to discover all available pages before exploring further. # Introspect token > **Visibility:** `public` · `internal` ( OpenAPI Custom Extension: x-visibility ) Determine whether an access token is currently active and return its claims. Inspired by RFC 7662 (OAuth 2.0 Token Introspection) but uses application/json instead of form-encoded requests. A token is considered active when all of the following are true: - The token has not expired. - The token has not been revoked. - The underlying credential (API key, service account credential) is still active and not disabled. - The parent principal (user, service account) is still active. This endpoint is intended for resource servers that need to validate a token beyond signature verification — for example, before executing sensitive operations where even a short-lived token should be checked against the current credential state. The caller must be authenticated (typically a resource server using its own service account credentials). ## OpenAPI ````yaml api-docs/k0rdent-api.json post /v1/regions/global/auth/introspect openapi: 3.1.0 info: title: K0rdent AI API version: 0.2.0-draft description: > OpenAPI specification for the K0rdent AI GPU-as-a-Service platform. **Custom Extensions:** - `x-visibility`: Endpoint visibility — `internal` (Atlas only), `public` (Arc only), `[internal, public]` (common) - `x-status`: Implementation status — `mvp`, `tbd`, `blocked`, `stretch` - `x-source`: Source document reference or `TBD` for fields pending confirmation **Error Model:** Standard `{ error: { code, message, details[] } }` envelope. **Pagination:** All list endpoints support two modes: - **Cursor** (`pageToken` + `pageSize`): Use for frequently updated resources. Prevents skipped or duplicated items across pages. `nextPageToken` is returned; `total` is not. - **Offset** (`offset` + `pageSize`): Use for stable resources. Returns `total` for page-count UIs. `nextPageToken` is not returned. `pageToken` and `offset` are mutually exclusive. Default `pageSize` is 50, maximum is 500. servers: - url: https://api.k0rdent.ai description: K0rdent AI API Gateway security: - bearerAuth: [] tags: - name: clusters description: Kubernetes cluster management - name: kubeconfigs description: Kubeconfig issuance and management - name: instances description: VM and baremetal instance lifecycle - name: networks description: Network configuration and topology - name: addresses description: IP address management - name: servers description: Bare metal server lifecycle management - name: organizations description: Organization (tenant) management - name: projects description: Project resource grouping - name: authentication description: Authentication and session management - name: users description: User management - name: groups description: User group management - name: roles description: RBAC role definitions - name: policies description: IAM policy bindings - name: providers description: Identity provider configuration - name: token description: > Generate access token via multiple grant types (authorization_code, api_key, client_credentials). - name: check description: > Evaluate permissions for a principal against actions and resources. Supports single and bulk checks (up to 100). - name: introspect description: > Token introspection per RFC 7662. Validate token activity and retrieve full decoded claims. - name: revoke description: > Token revocation per RFC 7009. Explicitly invalidate access tokens before natural expiration. - name: sessions description: > Manage user browser sessions. Supports listing active sessions, creating a new session (login), and ending the current session (logout). - name: apikeys description: > Manage API keys for programmatic access. API keys are bound to a user and inherit a dynamic subset of the user's privileges, evaluated at token-mint time. Keys are scoped to a level in the resource hierarchy (organization, or project). - name: serviceaccounts description: | Manage service accounts for machine-to-machine and infrastructure access. Service accounts are independent principals with their own identity, role bindings, and credentials. They survive user off-boarding and are managed exclusively by tenant administrators. paths: /v1/regions/global/auth/introspect: post: tags: - introspect summary: Introspect token description: > **Visibility:** `public` · `internal` ( OpenAPI Custom Extension: x-visibility ) Determine whether an access token is currently active and return its claims. Inspired by RFC 7662 (OAuth 2.0 Token Introspection) but uses application/json instead of form-encoded requests. A token is considered active when all of the following are true: - The token has not expired. - The token has not been revoked. - The underlying credential (API key, service account credential) is still active and not disabled. - The parent principal (user, service account) is still active. This endpoint is intended for resource servers that need to validate a token beyond signature verification — for example, before executing sensitive operations where even a short-lived token should be checked against the current credential state. The caller must be authenticated (typically a resource server using its own service account credentials). operationId: introspectToken requestBody: required: true content: application/json: schema: type: object required: - token properties: token: type: string description: The access token (JWT) to introspect. responses: '200': description: | Introspection result. If the token is active, the full claim set is returned. If inactive, only active: false is returned — no claims are exposed for invalid tokens. content: application/json: schema: oneOf: - $ref: '#/components/schemas/ActiveIntrospectionResponse' - $ref: '#/components/schemas/InactiveIntrospectionResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: schemas: ActiveIntrospectionResponse: type: object description: | Returned when the token is valid and active. Includes the full decoded claim set per RFC 7662. required: - active - sub - iss - aud - exp - iat - jti - tenant_id - scope - scope_id - roles - principal_type properties: active: type: boolean enum: - true description: Token is active. sub: type: string description: | Subject — the principal identifier. User ID for interactive sessions and API keys, service account clientId for client_credentials. example: user-xyz789 iss: type: string description: Issuer URL. example: https://auth.platform.example.com aud: type: string description: Intended audience. exp: type: integer description: Expiration time (Unix timestamp). iat: type: integer description: Issued-at time (Unix timestamp). jti: type: string description: Unique token identifier. tenant_id: type: string description: Organization/tenant identifier. example: org-acme scope: type: string enum: - organization - project description: | The resource hierarchy level this token is scoped to. scope_id: type: string description: | Resource identifier for the token's scope boundary. example: proj-abc123 roles: type: array items: type: string description: | Effective roles for this token. For API keys, this is the intersection of the key's roles and the user's current roles. For service accounts, these are the directly assigned roles. May be further narrowed if scope narrowing was applied at mint time. example: - viewer - member principal_type: type: string enum: - user - api_key - service_account description: | How the caller authenticated. Allows downstream services to apply principal-type-specific policies. credential_id: type: string description: | Identifier of the credential used to mint this token. API key ID for api_key grants, credential ID for client_credentials grants. Null for interactive sessions. example: apikey-j2k3l4 InactiveIntrospectionResponse: type: object description: | Returned when the token is invalid, expired, revoked, or the underlying credential/principal is inactive. No claims are exposed for security — only the active flag is returned. required: - active properties: active: type: boolean enum: - false description: Token is not active. Error: type: object description: Standard error response properties: error: type: object properties: code: type: integer description: HTTP status code message: type: string description: Error message details: type: array items: type: object description: Additional error details responses: BadRequest: description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: Bearer token authentication using OAuth2/OIDC tokens ````