openapi: 3.1.0
info:
  title: Supabase Auth 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
externalDocs:
  description: Supabase Auth Documentation
  url: https://supabase.com/docs/guides/auth
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
tags:
  - name: Admin
    description: >-
      Administrative endpoints for managing users. Requires service_role key.
  - name: Authentication
    description: >-
      User signup, signin, and token management endpoints.
  - name: Configuration
    description: >-
      Server configuration and settings endpoints.
  - name: MFA
    description: >-
      Multi-factor authentication enrollment and verification endpoints.
  - name: OAuth
    description: >-
      OAuth social login provider endpoints.
  - name: SSO
    description: >-
      SAML-based single sign-on endpoints.
  - name: User Management
    description: >-
      Endpoints for managing the currently authenticated user profile.
security:
  - apiKeyAuth: []
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
  /user:
    get:
      operationId: getUser
      summary: Get the current user
      description: >-
        Returns the user object for the currently authenticated user based
        on the access token in the Authorization header.
      tags:
        - User Management
      security:
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
    put:
      operationId: updateUser
      summary: Update the current user
      description: >-
        Updates the currently authenticated user's profile data including
        email, phone, password, and custom user metadata.
      tags:
        - User Management
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: User updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '422':
          description: Unprocessable entity
  /authorize:
    get:
      operationId: authorizeOAuth
      summary: Initiate OAuth login
      description: >-
        Redirects the user to the specified OAuth provider's authorization
        page. After the user grants access, they are redirected back to the
        application with an authorization code or tokens.
      tags:
        - OAuth
      parameters:
        - name: provider
          in: query
          required: true
          schema:
            type: string
            enum:
              - google
              - github
              - gitlab
              - bitbucket
              - azure
              - facebook
              - apple
              - twitter
              - discord
              - twitch
              - spotify
              - slack
              - linkedin
              - notion
              - zoom
              - keycloak
              - workos
              - figma
              - kakao
              - fly
          description: The OAuth provider to authenticate with
        - name: redirect_to
          in: query
          schema:
            type: string
            format: uri
          description: URL to redirect to after authentication
        - name: scopes
          in: query
          schema:
            type: string
          description: Space-separated list of OAuth scopes to request
      responses:
        '302':
          description: Redirect to OAuth provider
        '400':
          description: Bad request - invalid provider
  /callback:
    get:
      operationId: oauthCallback
      summary: OAuth callback
      description: >-
        Receives the OAuth callback from the provider after user authorization.
        Exchanges the authorization code for tokens and creates or updates
        the user account.
      tags:
        - OAuth
      parameters:
        - name: code
          in: query
          schema:
            type: string
          description: Authorization code from the OAuth provider
        - name: state
          in: query
          schema:
            type: string
          description: State parameter for CSRF protection
      responses:
        '303':
          description: Redirect to application with session
        '400':
          description: Invalid callback parameters
  /factors:
    post:
      operationId: enrollMfaFactor
      summary: Enroll an MFA factor
      description: >-
        Enrolls a new multi-factor authentication factor for the authenticated
        user. Supports TOTP (time-based one-time password) authenticator apps.
      tags:
        - MFA
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollMfaRequest'
      responses:
        '200':
          description: MFA factor enrolled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaFactor'
        '401':
          description: Unauthorized
  /factors/{factorId}/challenge:
    post:
      operationId: challengeMfaFactor
      summary: Create an MFA challenge
      description: >-
        Creates a challenge for a specific MFA factor, prompting the user to
        provide verification from their authenticator device.
      tags:
        - MFA
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FactorId'
      responses:
        '200':
          description: Challenge created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MfaChallenge'
        '401':
          description: Unauthorized
        '404':
          description: Factor not found
  /factors/{factorId}/verify:
    post:
      operationId: verifyMfaFactor
      summary: Verify an MFA challenge
      description: >-
        Verifies an MFA challenge by providing the code from the authenticator
        device. On success, the session is upgraded to an authenticated
        assurance level.
      tags:
        - MFA
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/FactorId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - challenge_id
                - code
              properties:
                challenge_id:
                  type: string
                  format: uuid
                  description: ID of the challenge to verify
                code:
                  type: string
                  description: TOTP code from the authenticator
                  minLength: 6
                  maxLength: 6
      responses:
        '200':
          description: Verification successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthResponse'
        '400':
          description: Invalid code
        '401':
          description: Unauthorized
  /admin/users:
    get:
      operationId: adminListUsers
      summary: List all users (admin)
      description: >-
        Returns a paginated list of all users in the project. Requires
        service_role key authentication.
      tags:
        - Admin
      security:
        - bearerAuth: []
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
          description: Page number for pagination
        - name: per_page
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
          description: Number of users per page
      responses:
        '200':
          description: Successfully retrieved users
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  aud:
                    type: string
                    description: Audience claim
        '401':
          description: Unauthorized
    post:
      operationId: adminCreateUser
      summary: Create a user (admin)
      description: >-
        Creates a new user without requiring email confirmation. Requires
        service_role key authentication.
      tags:
        - Admin
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminCreateUserRequest'
      responses:
        '200':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /admin/users/{user_id}:
    get:
      operationId: adminGetUser
      summary: Get a user by ID (admin)
      description: >-
        Retrieves a specific user by their UUID. Requires service_role key
        authentication.
      tags:
        - Admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Successfully retrieved user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
        '404':
          description: User not found
    put:
      operationId: adminUpdateUser
      summary: Update a user (admin)
      description: >-
        Updates a user's profile, role, or confirmation status. Requires
        service_role key authentication.
      tags:
        - Admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminUpdateUserRequest'
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
        '404':
          description: User not found
    delete:
      operationId: adminDeleteUser
      summary: Delete a user (admin)
      description: >-
        Permanently deletes a user and their associated data. Requires
        service_role key authentication.
      tags:
        - Admin
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: User deleted
        '401':
          description: Unauthorized
        '404':
          description: User not found
  /invite:
    post:
      operationId: inviteUser
      summary: Invite a user by email
      description: >-
        Sends an invitation email to the specified address. The recipient can
        use the link in the email to create their account. Requires
        service_role key authentication.
      tags:
        - Admin
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to invite
                data:
                  type: object
                  description: Custom user metadata to set on the invited user
      responses:
        '200':
          description: Invitation sent
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '422':
          description: User already exists
  /sso/saml/acs:
    post:
      operationId: samlAcs
      summary: SAML Assertion Consumer Service
      description: >-
        Receives the SAML assertion from an identity provider after successful
        authentication. This endpoint processes the assertion and creates or
        updates the user session.
      tags:
        - SSO
      responses:
        '303':
          description: Redirect to application with session
        '400':
          description: Invalid SAML assertion
  /settings:
    get:
      operationId: getSettings
      summary: Get auth settings
      description: >-
        Returns the publicly available auth server settings including enabled
        providers, auto-confirm settings, and external provider configurations.
        This endpoint does not require authentication.
      tags:
        - Configuration
      security: []
      responses:
        '200':
          description: Successfully retrieved settings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthSettings'
components:
  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.
  parameters:
    FactorId:
      name: factorId
      in: path
      required: true
      description: UUID of the MFA factor
      schema:
        type: string
        format: uuid
    UserId:
      name: user_id
      in: path
      required: true
      description: UUID of the user
      schema:
        type: string
        format: uuid
  schemas:
    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
    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
    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
    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
    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
    UpdateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          description: New email address
        phone:
          type: string
          description: New phone number
        password:
          type: string
          description: New password
          minLength: 6
        data:
          type: object
          description: Custom user metadata to update
        nonce:
          type: string
          description: Nonce for reauthentication when changing password
    AdminCreateUserRequest:
      type: object
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: User email address
        phone:
          type: string
          description: User phone number
        password:
          type: string
          description: User password
        email_confirm:
          type: boolean
          description: Whether to auto-confirm the email
          default: false
        phone_confirm:
          type: boolean
          description: Whether to auto-confirm the phone
          default: false
        user_metadata:
          type: object
          description: Custom user metadata
        app_metadata:
          type: object
          description: Application-level metadata
        role:
          type: string
          description: User role
        ban_duration:
          type: string
          description: Duration to ban user (e.g. 24h, none)
    AdminUpdateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          description: New email address
        phone:
          type: string
          description: New phone number
        password:
          type: string
          description: New password
        email_confirm:
          type: boolean
          description: Whether to confirm the email
        phone_confirm:
          type: boolean
          description: Whether to confirm the phone
        user_metadata:
          type: object
          description: Custom user metadata
        app_metadata:
          type: object
          description: Application-level metadata
        role:
          type: string
          description: User role
        ban_duration:
          type: string
          description: Duration to ban user (e.g. 24h, none to unban)
    EnrollMfaRequest:
      type: object
      required:
        - factor_type
      properties:
        factor_type:
          type: string
          description: Type of MFA factor to enroll
          enum:
            - totp
        friendly_name:
          type: string
          description: Human-readable name for the factor
        issuer:
          type: string
          description: Issuer name displayed in authenticator apps
    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'
    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
    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
    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
    MfaChallenge:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique challenge identifier
        expires_at:
          type: string
          format: date-time
          description: Timestamp when the challenge expires
    AuthSettings:
      type: object
      properties:
        external:
          type: object
          description: External OAuth provider configurations
          additionalProperties:
            type: boolean
        disable_signup:
          type: boolean
          description: Whether new signups are disabled
        mailer_autoconfirm:
          type: boolean
          description: Whether emails are auto-confirmed
        phone_autoconfirm:
          type: boolean
          description: Whether phones are auto-confirmed
        sms_provider:
          type: string
          description: SMS provider in use