> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kynasmith.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Mint Access Token

> Exchange a long-lived machine credential for a short-lived access token.



## OpenAPI

````yaml /generated/api.openapi.json post /api/auth/access-tokens
openapi: 3.1.0
info:
  title: Kynasmith Public API
  version: 0.1.0
servers: []
security: []
paths:
  /api/auth/access-tokens:
    post:
      tags:
        - machine-auth
      summary: Mint Access Token
      description: Exchange a long-lived machine credential for a short-lived access token.
      operationId: mint_access_token_api_auth_access_tokens_post
      parameters:
        - in: header
          name: Idempotency-Key
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Idempotency-Key
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccessTokenExchangeRequest'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessTokenResponse'
          description: Successful Response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Authentication failed.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Caller is not authorized for this action.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Referenced resource does not exist.
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Request conflicts with current resource state.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorEnvelope'
          description: Request validation failed for the targeted resource state.
components:
  schemas:
    AccessTokenExchangeRequest:
      description: >-
        Machine credential exchange request for ``POST
        /api/auth/access-tokens``.


        **Migration path (#6, #53):**


        The preferred shape is evolving toward ``{ api_key, scopes? }`` where
        the

        project scope is inferred from the authenticated credential. During the

        migration window both the legacy dual-credential shape and the
        simplified

        ``api_key`` shorthand are accepted.


        When ``project_id`` is omitted the API infers the project scope from the

        authenticated credential. When provided, the API validates it matches.
      properties:
        api_key:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Simplified API key secret. When provided as the sole credential
            field, the backend resolves the key by its secret hash. Preferred
            over the legacy api_key_id + api_key_secret pair.
          title: Api Key
        api_key_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: API key identifier, if using the legacy credential pair.
          title: Api Key Id
        api_key_secret:
          anyOf:
            - type: string
            - type: 'null'
          description: API key secret, if using the legacy credential pair.
          title: Api Key Secret
        project_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: >-
            Explicit project context for the access token request. When omitted,
            inferred from the authenticated credential.
          title: Project Id
        scopes:
          description: Requested access-token scopes.
          items:
            type: string
          title: Scopes
          type: array
        service_account_id:
          anyOf:
            - format: uuid
              type: string
            - type: 'null'
          description: Service-account identifier, if using a service account.
          title: Service Account Id
        service_account_secret:
          anyOf:
            - type: string
            - type: 'null'
          description: Service-account secret, if using a service account.
          title: Service Account Secret
      title: AccessTokenExchangeRequest
      type: object
    AccessTokenResponse:
      description: Access-token exchange response.
      properties:
        access_token:
          description: Short-lived backend-signed access token.
          title: Access Token
          type: string
        expires_in_seconds:
          description: Access-token lifetime in seconds.
          title: Expires In Seconds
          type: integer
        organization_id:
          description: Bound organization identifier.
          format: uuid
          title: Organization Id
          type: string
        project_id:
          description: Bound project identifier.
          format: uuid
          title: Project Id
          type: string
        token_type:
          const: Bearer
          default: Bearer
          description: Bearer token type marker.
          title: Token Type
          type: string
      required:
        - access_token
        - expires_in_seconds
        - organization_id
        - project_id
      title: AccessTokenResponse
      type: object
    PublicErrorEnvelope:
      description: Stable public error envelope shared across transports.
      properties:
        error:
          $ref: '#/components/schemas/PublicErrorDetail'
          description: Structured error payload.
      required:
        - error
      title: PublicErrorEnvelope
      type: object
    PublicErrorDetail:
      description: Stable public error payload shared across transports.
      properties:
        code:
          description: Machine-readable error code.
          title: Code
          type: string
        details:
          additionalProperties:
            anyOf:
              - type: string
              - type: integer
              - type: number
              - type: boolean
              - type: 'null'
          description: Bounded structured error details.
          title: Details
          type: object
        message:
          description: Human-readable error message.
          title: Message
          type: string
        retryable:
          description: Whether the caller can retry safely.
          title: Retryable
          type: boolean
      required:
        - code
        - message
        - retryable
      title: PublicErrorDetail
      type: object

````