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

# Exchange Code or Refresh Token for Tokens

> Used to exchange an `authorization_code` for tokens, or to use a `refresh_token` to get a new `access_token`. Client authentication can be performed via `client_secret_post` (in the body), `client_secret_basic` (HTTP Basic Auth), or `private_key_jwt`.




## OpenAPI

````yaml /api/en/authentication.yaml post /oauth/token
openapi: 3.0.3
info:
  title: Altostrat Authentication API
  description: >
    This document provides a comprehensive guide to Altostrat's Authentication
    API. It leverages Auth0 to provide secure, stateless, JWT-based
    authentication for the Altostrat Single-Page Application (SPA). The
    authentication mechanism is built on the industry-standard **OAuth 2.0
    Authorization Code Flow with Proof Key for Code Exchange (PKCE)**, ensuring
    robust security for client-side applications.


    This documentation is a strategic blueprint designed for developers to
    accelerate integration. It details not only the API endpoints but also the
    underlying standards like **OpenID Connect (OIDC)** and the structure of the
    JSON Web Tokens (JWTs) used for authorization. Developers can use the OIDC
    discovery endpoint to auto-configure their clients.


    ### Authentication Flow Overview:

    1.  **Initiate Login:** The Altostrat web application initiates the
    authentication flow by redirecting the user's browser to the `/authorize`
    endpoint.

    2.  **User Authentication & Consent:** The user authenticates on the
    `signin.altostrat.io` domain and grants the application permission to access
    the requested scopes.

    3.  **Receive Authorization Code:** Auth0 redirects the user back to the
    Altostrat application's registered callback URL with a single-use
    `authorization_code`.

    4.  **Exchange Code for Tokens:** The Altostrat application's backend sends
    the `authorization_code` along with the `code_verifier` to the
    `/oauth/token` endpoint.

    5.  **Receive Tokens & Call APIs:** A successful exchange provides an
    `access_token` (JWT), an `id_token`, and a `refresh_token`. The
    `access_token` is then used as a Bearer token to make secure calls to
    Altostrat's resource APIs (e.g., `https://v1.api.altostrat.io`).
  version: 1.0.0
servers:
  - url: https://signin.altostrat.io
    description: Altostrat OAuth 2.0 & OpenID Connect Infrastructure
security: []
tags:
  - name: OAuth 2.0 & OIDC
    description: >-
      Core endpoints for the authentication, token management, and session
      flows.
  - name: Discovery
    description: >-
      Standard OpenID Connect discovery endpoints for automatic client
      configuration.
paths:
  /oauth/token:
    post:
      tags:
        - OAuth 2.0 & OIDC
      summary: Exchange Code or Refresh Token for Tokens
      description: >
        Used to exchange an `authorization_code` for tokens, or to use a
        `refresh_token` to get a new `access_token`. Client authentication can
        be performed via `client_secret_post` (in the body),
        `client_secret_basic` (HTTP Basic Auth), or `private_key_jwt`.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - $ref: '#/components/schemas/AuthCodeGrantRequest'
                - $ref: '#/components/schemas/RefreshTokenGrantRequest'
      responses:
        '200':
          description: Successfully exchanged for a new set of tokens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: >-
            Bad Request. Malformed request, expired `code`, or incorrect
            `code_verifier`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    AuthCodeGrantRequest:
      type: object
      properties:
        grant_type:
          type: string
          enum:
            - authorization_code
        client_id:
          type: string
        code:
          type: string
        redirect_uri:
          type: string
          format: uri
        code_verifier:
          type: string
    RefreshTokenGrantRequest:
      type: object
      properties:
        grant_type:
          type: string
          enum:
            - refresh_token
        client_id:
          type: string
        refresh_token:
          type: string
    TokenResponse:
      type: object
      properties:
        access_token:
          type: string
          description: The JWT used to call protected APIs. See `AccessTokenPayload`.
        refresh_token:
          type: string
          description: A long-lived token for obtaining a new `access_token`.
        id_token:
          type: string
          description: A JWT containing user profile information (claims).
        token_type:
          type: string
          example: Bearer
        expires_in:
          type: integer
          example: 86400
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string

````