openapi: 3.1.0
info:
  title: Supabase Auth Admin Authentication API
  description: The Supabase Auth API (based on GoTrue) is a JWT-based API for managing users and issuing access tokens. It provides endpoints for user signup, signin with email/password, magic links, one-time passwords, OAuth social login, token refresh, user management, multi-factor authentication, and SAML-based single sign-on. When deployed on Supabase, the server requires an apikey header containing a valid Supabase-issued API key.
  version: 2.0.0
  contact:
    name: Supabase Support
    url: https://supabase.com/support
  termsOfService: https://supabase.com/terms
servers:
- url: https://{project_ref}.supabase.co/auth/v1
  description: Supabase Project Auth Server
  variables:
    project_ref:
      description: Your Supabase project reference ID
      default: your-project-ref
security:
- apiKeyAuth: []
tags:
- name: Authentication
  description: User signup, signin, and token management endpoints.
paths:
  /signup:
    post:
      operationId: signUp
      summary: Sign up a new user
      description: Creates a new user account with email and password, or phone and password. Returns the user object and session tokens. A confirmation email or SMS may be sent depending on project configuration.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignUpRequest'
      responses:
        '200':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: Bad request - invalid email or password
        '422':
          description: Unprocessable entity - user already exists
  /token:
    post:
      operationId: signIn
      summary: Sign in with credentials
      description: Authenticates a user with their credentials and returns a session including access and refresh tokens. The grant_type parameter determines the authentication method.
      tags:
      - Authentication
      parameters:
      - name: grant_type
        in: query
        required: true
        description: The type of authentication grant to use.
        schema:
          type: string
          enum:
          - password
          - refresh_token
          - id_token
          - pkce
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/PasswordGrantRequest'
              - $ref: '#/components/schemas/RefreshTokenGrantRequest'
              - $ref: '#/components/schemas/IdTokenGrantRequest'
      responses:
        '200':
          description: Authentication successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: Bad request - invalid credentials or grant type
        '401':
          description: Invalid login credentials
  /otp:
    post:
      operationId: sendOtp
      summary: Send a one-time password
      description: Sends a one-time password to the specified email or phone number. If the email template uses a confirmation URL variable, a magic link is sent instead. The OTP can be verified using the /verify endpoint.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OtpRequest'
      responses:
        '200':
          description: OTP sent successfully
        '400':
          description: Bad request
        '429':
          description: Rate limit exceeded
  /magiclink:
    post:
      operationId: sendMagicLink
      summary: Send a magic link
      description: Sends a magic link email to the specified address for passwordless authentication. The user clicks the link to be authenticated.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to send the magic link to
      responses:
        '200':
          description: Magic link sent successfully
        '400':
          description: Bad request
        '429':
          description: Rate limit exceeded
  /recover:
    post:
      operationId: recoverPassword
      summary: Send password recovery email
      description: Sends a password recovery email to the specified address containing a link that allows the user to reset their password.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address for password recovery
      responses:
        '200':
          description: Recovery email sent
        '400':
          description: Bad request
        '429':
          description: Rate limit exceeded
  /verify:
    post:
      operationId: verifyOtp
      summary: Verify an OTP or token hash
      description: Verifies a one-time password or token hash received via email or SMS. Supports different verification types including signup, recovery, invite, magiclink, email_change, and phone_change.
      tags:
      - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyOtpRequest'
      responses:
        '200':
          description: Verification successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: Bad request - invalid or expired OTP
    get:
      operationId: verifyOtpRedirect
      summary: Verify OTP via redirect
      description: Verifies a token hash from a magic link or email confirmation redirect. This endpoint is typically called by clicking the link in the email.
      tags:
      - Authentication
      parameters:
      - name: token_hash
        in: query
        required: true
        schema:
          type: string
        description: The token hash from the email link
      - name: type
        in: query
        required: true
        schema:
          type: string
          enum:
          - signup
          - recovery
          - invite
          - magiclink
          - email_change
        description: Type of verification
      - name: redirect_to
        in: query
        schema:
          type: string
          format: uri
        description: URL to redirect to after verification
      responses:
        '303':
          description: Redirect to application with tokens
        '400':
          description: Invalid or expired token
  /logout:
    post:
      operationId: signOut
      summary: Sign out a user
      description: Invalidates the user's current session and refresh token. Requires a valid access token in the Authorization header.
      tags:
      - Authentication
      parameters:
      - name: scope
        in: query
        schema:
          type: string
          enum:
          - local
          - global
          - others
        description: Scope of logout. Local revokes only the current session, global revokes all sessions, others revokes all other sessions.
      security:
      - bearerAuth: []
      responses:
        '204':
          description: Successfully signed out
        '401':
          description: Unauthorized - invalid or missing token
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique user identifier
        aud:
          type: string
          description: Audience claim
        role:
          type: string
          description: User role
        email:
          type: string
          format: email
          description: User email address
        email_confirmed_at:
          type: string
          format: date-time
          description: Timestamp when email was confirmed
        phone:
          type: string
          description: User phone number
        phone_confirmed_at:
          type: string
          format: date-time
          description: Timestamp when phone was confirmed
        confirmed_at:
          type: string
          format: date-time
          description: Timestamp when user was confirmed
        last_sign_in_at:
          type: string
          format: date-time
          description: Timestamp of last sign-in
        app_metadata:
          type: object
          properties:
            provider:
              type: string
              description: Primary authentication provider
            providers:
              type: array
              items:
                type: string
              description: List of linked authentication providers
          description: Application-level metadata
        user_metadata:
          type: object
          description: Custom user metadata
        identities:
          type: array
          items:
            $ref: '#/components/schemas/Identity'
          description: Linked identity providers
        factors:
          type: array
          items:
            $ref: '#/components/schemas/MfaFactor'
          description: Enrolled MFA factors
        created_at:
          type: string
          format: date-time
          description: Timestamp when user was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when user was last updated
    AuthResponse:
      type: object
      properties:
        access_token:
          type: string
          description: JWT access token for authenticating API requests
        token_type:
          type: string
          description: Token type, always bearer
          enum:
          - bearer
        expires_in:
          type: integer
          description: Number of seconds until the access token expires
        expires_at:
          type: integer
          description: Unix timestamp when the access token expires
        refresh_token:
          type: string
          description: Token used to obtain a new access token
        user:
          $ref: '#/components/schemas/User'
    RefreshTokenGrantRequest:
      type: object
      required:
      - refresh_token
      properties:
        refresh_token:
          type: string
          description: Refresh token from a previous authentication
    IdTokenGrantRequest:
      type: object
      required:
      - provider
      - id_token
      properties:
        provider:
          type: string
          description: OAuth provider that issued the ID token
          enum:
          - google
          - apple
          - azure
          - facebook
        id_token:
          type: string
          description: ID token from the OAuth provider
        nonce:
          type: string
          description: Nonce used during token generation
    MfaFactor:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique factor identifier
        friendly_name:
          type: string
          description: Human-readable name for the factor
        factor_type:
          type: string
          description: Type of MFA factor
          enum:
          - totp
        status:
          type: string
          description: Factor status
          enum:
          - verified
          - unverified
        created_at:
          type: string
          format: date-time
          description: Timestamp when factor was created
        updated_at:
          type: string
          format: date-time
          description: Timestamp when factor was last updated
    Identity:
      type: object
      properties:
        id:
          type: string
          description: Unique identity identifier
        user_id:
          type: string
          format: uuid
          description: ID of the associated user
        identity_data:
          type: object
          description: Data from the identity provider
        provider:
          type: string
          description: Identity provider name
        last_sign_in_at:
          type: string
          format: date-time
          description: Timestamp of last sign-in with this identity
        created_at:
          type: string
          format: date-time
          description: Timestamp when identity was linked
        updated_at:
          type: string
          format: date-time
          description: Timestamp when identity was last updated
    PasswordGrantRequest:
      type: object
      required:
      - password
      properties:
        email:
          type: string
          format: email
          description: User email address
        phone:
          type: string
          description: User phone number
        password:
          type: string
          description: User password
    SignUpRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          description: User email address
        phone:
          type: string
          description: User phone number in E.164 format
        password:
          type: string
          description: User password
          minLength: 6
        data:
          type: object
          description: Custom user metadata
        gotrue_meta_security:
          type: object
          properties:
            captcha_token:
              type: string
              description: Captcha verification token
    VerifyOtpRequest:
      type: object
      required:
      - type
      properties:
        type:
          type: string
          description: Type of verification
          enum:
          - signup
          - recovery
          - invite
          - magiclink
          - email_change
          - phone_change
          - sms
          - email
        token:
          type: string
          description: OTP code to verify
        token_hash:
          type: string
          description: Token hash from the email link
        email:
          type: string
          format: email
          description: Email address the OTP was sent to
        phone:
          type: string
          description: Phone number the OTP was sent to
        redirect_to:
          type: string
          format: uri
          description: URL to redirect to after verification
    OtpRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Email address to send OTP to
        phone:
          type: string
          description: Phone number to send OTP to
        create_user:
          type: boolean
          description: Whether to create a new user if one does not exist
          default: true
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: Supabase project API key (anon key for public operations, service_role key for admin operations).
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from a successful authentication.
externalDocs:
  description: Supabase Auth Documentation
  url: https://supabase.com/docs/guides/auth