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

# Callback

> Complete OAuth authorization flow.

Validates the state token, exchanges the authorization code for tokens,
and creates or updates the user record. Returns JWT tokens.

Flow:
1. Validate state token and check expiration
2. Resolve provider configuration
3. Exchange code for tokens via provider handler
4. Fetch user info via provider handler
5. Link to existing user or create new user/account
6. Generate JWT tokens and return response



## OpenAPI

````yaml post /api/v1/auth/oauth/{provider_name}/callback
openapi: 3.1.0
info:
  title: SnackBase
  description: Open-source Backend-as-a-Service (BaaS)
  version: 0.1.0
servers: []
security: []
paths:
  /api/v1/auth/oauth/{provider_name}/callback:
    post:
      tags:
        - auth
      summary: Callback
      description: |-
        Complete OAuth authorization flow.

        Validates the state token, exchanges the authorization code for tokens,
        and creates or updates the user record. Returns JWT tokens.

        Flow:
        1. Validate state token and check expiration
        2. Resolve provider configuration
        3. Exchange code for tokens via provider handler
        4. Fetch user info via provider handler
        5. Link to existing user or create new user/account
        6. Generate JWT tokens and return response
      operationId: callback_api_v1_auth_oauth__provider_name__callback_post
      parameters:
        - name: provider_name
          in: path
          required: true
          schema:
            type: string
            title: Provider Name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthCallbackRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OAuthCallbackResponse'
        '400':
          description: Invalid state or OAuth error
        '401':
          description: Inactive user
        '404':
          description: Provider not configured
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    OAuthCallbackRequest:
      properties:
        code:
          type: string
          title: Code
          description: Authorization code from provider
        state:
          type: string
          title: State
          description: State token for CSRF protection
        redirect_uri:
          type: string
          title: Redirect Uri
          description: Original redirect URI used in authorize request
      type: object
      required:
        - code
        - state
        - redirect_uri
      title: OAuthCallbackRequest
      description: Request body for OAuth callback completion.
    OAuthCallbackResponse:
      properties:
        token:
          type: string
          title: Token
          description: JWT access token
        refresh_token:
          type: string
          title: Refresh Token
          description: JWT refresh token
        expires_in:
          type: integer
          title: Expires In
          description: Access token expiration time in seconds
        account:
          $ref: '#/components/schemas/AccountResponse'
          description: Account information
        user:
          $ref: >-
            #/components/schemas/snackbase__infrastructure__api__schemas__auth_schemas__UserResponse
          description: User information
        is_new_user:
          type: boolean
          title: Is New User
          description: Whether a new user was created
        is_new_account:
          type: boolean
          title: Is New Account
          description: Whether a new account was created
      type: object
      required:
        - token
        - refresh_token
        - expires_in
        - account
        - user
        - is_new_user
        - is_new_account
      title: OAuthCallbackResponse
      description: Response for successful OAuth callback authentication.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AccountResponse:
      properties:
        id:
          type: string
          title: Id
          description: Account ID in XX#### format
        slug:
          type: string
          title: Slug
          description: URL-friendly account identifier
        name:
          type: string
          title: Name
          description: Display name for the account
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the account was created
      type: object
      required:
        - id
        - slug
        - name
        - created_at
      title: AccountResponse
      description: Account information in auth responses.
    snackbase__infrastructure__api__schemas__auth_schemas__UserResponse:
      properties:
        id:
          type: string
          title: Id
          description: User ID
        email:
          type: string
          title: Email
          description: User's email address
        role:
          type: string
          title: Role
          description: User's role name
        is_active:
          type: boolean
          title: Is Active
          description: Whether the user is active
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the user was created
      type: object
      required:
        - id
        - email
        - role
        - is_active
        - created_at
      title: UserResponse
      description: User information in auth responses.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````