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

# Initiate User Authentication

> This is the starting point for user authentication. The Altostrat web application redirects the user's browser to this endpoint to begin the OAuth 2.0 Authorization Code Flow with PKCE.




## OpenAPI

````yaml /api/en/authentication.yaml get /authorize
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:
  /authorize:
    get:
      tags:
        - OAuth 2.0 & OIDC
      summary: Initiate User Authentication
      description: >
        This is the starting point for user authentication. The Altostrat web
        application redirects the user's browser to this endpoint to begin the
        OAuth 2.0 Authorization Code Flow with PKCE.
      parameters:
        - name: response_type
          in: query
          required: true
          description: >-
            Specifies the response type. `code` is used for the Authorization
            Code Flow.
          schema:
            type: string
            enum:
              - code
              - token
              - id_token
              - code token
              - code id_token
              - token id_token
              - code token id_token
        - name: client_id
          in: query
          required: true
          description: The application's unique identifier.
          schema:
            type: string
        - name: redirect_uri
          in: query
          required: true
          description: >-
            The URL to which the user is redirected after authentication. Must
            be an allowed callback URL.
          schema:
            type: string
            format: uri
        - name: scope
          in: query
          required: true
          description: >-
            A space-separated list of permissions. `offline_access` is required
            to receive a refresh token.
          schema:
            type: string
          example: openid profile email offline_access
        - name: state
          in: query
          required: true
          description: An opaque value used to prevent CSRF attacks.
          schema:
            type: string
        - name: code_challenge
          in: query
          required: true
          description: The Base64-URL-encoded hash of the `code_verifier`.
          schema:
            type: string
        - name: code_challenge_method
          in: query
          required: true
          description: The method used to generate the challenge. `S256` is recommended.
          schema:
            type: string
            enum:
              - S256
              - plain
      responses:
        '302':
          description: >-
            Redirects the user to the Altostrat login page. After success,
            redirects back to the `redirect_uri`.

````