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

# Mint access token

> **Visibility:** `public` · `internal` ( OpenAPI Custom Extension: x-visibility )

Exchange a credential for a self-contained JWT access token.
This endpoint proxies to the underlying identity provider
for token issuance.

Three grant types are supported:

**authorization_code** — Interactive user session. Exchanges an
authorization code obtained from the OAuth2 /authorize flow.

**api_key** — Programmatic access via an API key. The caller
presents the opaque, prefixed API key token. Effective privileges
are evaluated as the intersection of the key's role list (if set)
and the creating user's current roles within the key's scope.

**client_credentials** — Service account authentication. The
caller presents a client_id and client_secret pair. Effective
privileges are the service account's directly assigned roles
within its scope.

All grant types support optional scope narrowing at mint time:
the caller can request a narrower scope and/or a subset of roles
for the issued token. The requested scope must be at or below the
credential's scope in the resource hierarchy, and the requested
roles must be a subset of the credential's effective roles.




## OpenAPI

````yaml api-docs/k0rdent-api.json post /v1/regions/global/auth/token
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/token:
    post:
      tags:
        - token
      summary: Mint access token
      description: >
        **Visibility:** `public` · `internal` ( OpenAPI Custom Extension:
        x-visibility )


        Exchange a credential for a self-contained JWT access token.

        This endpoint proxies to the underlying identity provider

        for token issuance.


        Three grant types are supported:


        **authorization_code** — Interactive user session. Exchanges an

        authorization code obtained from the OAuth2 /authorize flow.


        **api_key** — Programmatic access via an API key. The caller

        presents the opaque, prefixed API key token. Effective privileges

        are evaluated as the intersection of the key's role list (if set)

        and the creating user's current roles within the key's scope.


        **client_credentials** — Service account authentication. The

        caller presents a client_id and client_secret pair. Effective

        privileges are the service account's directly assigned roles

        within its scope.


        All grant types support optional scope narrowing at mint time:

        the caller can request a narrower scope and/or a subset of roles

        for the issued token. The requested scope must be at or below the

        credential's scope in the resource hierarchy, and the requested

        roles must be a subset of the credential's effective roles.
      operationId: mintToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - grant_type
              discriminator:
                propertyName: grant_type
                mapping:
                  authorization_code:
                    $ref: '#/components/schemas/AuthCodeGrant'
                  api_key:
                    $ref: '#/components/schemas/ApiKeyGrant'
                  client_credentials:
                    $ref: '#/components/schemas/ClientCredentialsGrant'
              oneOf:
                - $ref: '#/components/schemas/AuthCodeGrant'
                - $ref: '#/components/schemas/ApiKeyGrant'
                - $ref: '#/components/schemas/ClientCredentialsGrant'
      responses:
        '200':
          description: Token successfully minted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    AuthCodeGrant:
      type: object
      required:
        - grant_type
        - code
        - redirect_uri
      properties:
        grant_type:
          type: string
          enum:
            - authorization_code
        code:
          type: string
          description: Authorization code from the OAuth2 /authorize flow.
        redirect_uri:
          type: string
          format: uri
          description: |
            Redirect URI that was used in the authorization request.
            Must match exactly.
        scope_narrowing:
          $ref: '#/components/schemas/ScopeNarrowing'
    ApiKeyGrant:
      type: object
      required:
        - grant_type
        - api_key
      properties:
        grant_type:
          type: string
          enum:
            - api_key
        api_key:
          type: string
          description: |
            The opaque, prefixed API key token (e.g., plt_sk_...).
        scope_narrowing:
          $ref: '#/components/schemas/ScopeNarrowing'
    ClientCredentialsGrant:
      type: object
      required:
        - grant_type
        - client_id
        - client_secret
      properties:
        grant_type:
          type: string
          enum:
            - client_credentials
        client_id:
          type: string
          description: |
            Service account client identifier.
        client_secret:
          type: string
          description: |
            Credential secret for the service account.
        scope_narrowing:
          $ref: '#/components/schemas/ScopeNarrowing'
    TokenResponse:
      type: object
      required:
        - access_token
        - token_type
        - expires_in
      properties:
        access_token:
          type: string
          description: |
            Self-contained JWT access token. Contains claims for
            sub, iss, aud, exp, iat, jti, tenant_id, scope,
            scope_id, roles, and principal_type.
        token_type:
          type: string
          enum:
            - Bearer
          description: Token type. Always "Bearer".
        expires_in:
          type: integer
          description: Token lifetime in seconds.
          example: 900
        refresh_token:
          type: string
          description: |
            Refresh token for obtaining new access tokens without
            re-authentication. Only issued for the authorization_code
            grant type. Not issued for api_key or client_credentials
            grants.
    ScopeNarrowing:
      type: object
      description: |
        Optional scope narrowing for the minted token. When provided,
        the issued JWT will have a narrower scope and/or fewer roles
        than the credential's effective privileges. The requested
        scope must be at or below the credential's scope level in
        the hierarchy (org > project), and the requested
        roles must be a subset of the effective roles.
      properties:
        scope:
          type: string
          enum:
            - organization
            - project
          description: |
            Requested scope level for the token. Must be at or
            below the credential's scope level.
        scopeId:
          type: string
          description: |
            Resource identifier for the requested scope. Must be
            within the credential's scope boundary.
          example: proj-abc123
        roles:
          type: array
          items:
            type: string
          description: |
            Subset of roles to include in the token. Each must be
            within the credential's effective roles.
          example:
            - member
    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

````