openapi: 3.0.0
info:
  version: 1.0.0
  title: Nhost authentication API
  description: Comprehensive authentication service for managing user identities, sessions, and authentication methods
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  contact:
    name: Nhost Support
    email: support@nhost.io
    url: https://nhost.io
servers:
- url: https://{subdomain}.auth.{region}.nhost.run/v1
  description: Nhost Authentication API Server
tags:
- name: authentication
  description: User authentication operations including sign-in, sign-up, and various authentication methods (email/password, passwordless, OAuth, WebAuthn, MFA)
paths:
  /signin/anonymous:
    post:
      summary: Sign in anonymously
      description: Create an anonymous user session without providing credentials. Anonymous users can be converted to regular users later via the deanonymize endpoint.
      operationId: signInAnonymous
      tags:
      - authentication
      requestBody:
        description: Optional user profile information for anonymous sign-in
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInAnonymousRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionPayload'
          description: Successfully signed in
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/email-password:
    post:
      summary: Sign in with email and password
      description: Authenticate a user with their email and password. Returns a session object or MFA challenge if two-factor authentication is enabled.
      operationId: signInEmailPassword
      tags:
      - authentication
      requestBody:
        description: User credentials for email and password authentication
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInEmailPasswordRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignInEmailPasswordResponse'
          description: Authentication successful. If MFA is enabled, a challenge will be returned instead of a session.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/idtoken:
    post:
      summary: Sign in with an ID token
      description: Authenticate using an ID token from a supported OAuth provider (Apple or Google). Creates a new user account if one doesn't exist.
      operationId: signInIdToken
      tags:
      - authentication
      requestBody:
        description: ID token and provider information for authentication
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInIdTokenRequest'
        required: true
      responses:
        '200':
          description: Successfully signed in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionPayload'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/mfa/totp:
    post:
      summary: Verify TOTP for MFA
      description: Complete the multi-factor authentication by verifying a Time-based One-Time Password (TOTP). Returns a session if validation is successful.
      operationId: verifySignInMfaTotp
      tags:
      - authentication
      requestBody:
        description: MFA ticket and TOTP code for multi-factor authentication verification
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInMfaTotpRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionPayload'
          description: MFA verification successful, session created
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/otp/email:
    post:
      summary: Sign in with email OTP
      description: Initiate email-based one-time password authentication. Sends an OTP to the specified email address. If the user doesn't exist, a new account will be created with the provided options.
      operationId: signInOTPEmail
      tags:
      - authentication
      requestBody:
        description: Email address and optional user options for OTP authentication
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInOTPEmailRequest'
        required: true
      responses:
        '200':
          description: OTP sent to user's email successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OKResponse'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/otp/email/verify:
    post:
      summary: Verify email OTP
      description: Complete email OTP authentication by verifying the one-time password. Returns a session if validation is successful.
      operationId: verifySignInOTPEmail
      tags:
      - authentication
      requestBody:
        description: OTP code and email address for verification
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInOTPEmailVerifyRequest'
        required: true
      responses:
        '200':
          description: Magic link sent to user's email successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignInOTPEmailVerifyResponse'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/passwordless/email:
    post:
      summary: Sign in with magic link email
      description: Initiate passwordless authentication by sending a magic link to the user's email. If the user doesn't exist, a new account will be created with the provided options.
      operationId: signInPasswordlessEmail
      tags:
      - authentication
      requestBody:
        description: Email address and optional user options for magic link authentication
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInPasswordlessEmailRequest'
        required: true
      responses:
        '200':
          description: Magic link email sent successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OKResponse'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/passwordless/sms:
    post:
      operationId: signInPasswordlessSms
      summary: Sign in with SMS OTP
      description: Initiate passwordless authentication by sending a one-time password to the user's phone number. If the user doesn't exist, a new account will be created with the provided options.
      tags:
      - authentication
      requestBody:
        description: Phone number and optional user options for SMS OTP authentication
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInPasswordlessSmsRequest'
        required: true
      responses:
        '200':
          description: OTP sent to user's phone number successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OKResponse'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/passwordless/sms/otp:
    post:
      operationId: verifySignInPasswordlessSms
      summary: Verify SMS OTP
      description: Complete passwordless SMS authentication by verifying the one-time password. Returns a session if validation is successful.
      tags:
      - authentication
      requestBody:
        description: Phone number and OTP code for SMS verification
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInPasswordlessSmsOtpRequest'
        required: true
      responses:
        '200':
          description: User successfully authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignInPasswordlessSmsOtpResponse'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/pat:
    post:
      summary: Sign in with Personal Access Token (PAT)
      description: Authenticate using a Personal Access Token. PATs are long-lived tokens that can be used for programmatic access to the API.
      operationId: signInPAT
      tags:
      - authentication
      requestBody:
        description: Personal Access Token for authentication
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInPATRequest'
        required: true
      responses:
        '200':
          description: Successfully signed in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionPayload'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/provider/{provider}:
    get:
      summary: Sign in with an OAuth2 provider
      description: Initiate OAuth2 authentication flow with a social provider. Redirects the user to the provider's authorization page.
      operationId: signInProvider
      tags:
      - authentication
      parameters:
      - $ref: '#/components/parameters/SignInProvider'
      - name: allowedRoles
        in: query
        required: false
        description: Array of allowed roles for the user
        style: form
        explode: false
        schema:
          type: array
          items:
            type: string
          example:
          - me
          - user
      - name: defaultRole
        in: query
        required: false
        description: Default role for the user
        schema:
          type: string
          example: user
      - name: displayName
        in: query
        required: false
        description: Display name for the user
        schema:
          type: string
          pattern: ^[\p{L}\p{N}\p{S} ,.'-]+$
          maxLength: 32
          example: John Smith
      - name: locale
        in: query
        required: false
        description: A two-characters locale
        schema:
          type: string
          maxLength: 2
          minLength: 2
          example: en
      - name: metadata
        in: query
        required: false
        description: Additional metadata for the user (JSON encoded string)
        content:
          application/json:
            schema:
              type: object
              additionalProperties: true
              example:
                firstName: John
                lastName: Smith
      - name: redirectTo
        in: query
        required: false
        description: URI to redirect to
        schema:
          type: string
          format: uri
          example: https://my-app.com/catch-redirection
      - name: connect
        in: query
        required: false
        description: If set, this means that the user is already authenticated and wants to link their account. This needs to be a valid JWT access token.
        schema:
          type: string
      responses:
        '302':
          description: Redirect to social provider
          headers:
            Location:
              $ref: '#/components/headers/RedirectLocation'
          content: {}
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/provider/{provider}/callback:
    get:
      summary: OAuth2 provider callback endpoint
      description: Handles the callback from OAuth2 providers after user authorization. Processes the authorization code and creates a user session.
      operationId: signInProviderCallbackGet
      tags:
      - authentication
      parameters:
      - $ref: '#/components/parameters/SignInProvider'
      - name: code
        in: query
        description: Authorization code provided by the authentication provider
        schema:
          type: string
      - name: id_token
        in: query
        description: ID token provided by the authentication provider
        schema:
          type: string
      - name: state
        in: query
        required: true
        description: State parameter to avoid CSRF attacks
        schema:
          type: string
      - name: oauth_token
        in: query
        required: false
        description: OAuth token for the provider (e.g., X)
        schema:
          type: string
      - name: oauth_verifier
        in: query
        required: false
        description: OAuth verifier for the provider (e.g., X)
        schema:
          type: string
      - name: error
        in: query
        required: false
        description: Error message if authentication failed
        schema:
          type: string
      - name: error_description
        in: query
        required: false
        description: Detailed error description if authentication failed
        schema:
          type: string
      - name: error_uri
        in: query
        required: false
        description: URI with more information about the error
        schema:
          type: string
      responses:
        '302':
          description: Redirect to client application after successful authentication
          headers:
            Location:
              $ref: '#/components/headers/RedirectLocation'
          content: {}
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
    post:
      summary: OAuth2 provider callback endpoint (form_post)
      description: Handles OAuth2 provider callbacks using form_post response mode. Used by providers like Apple that send data via POST instead of query parameters.
      operationId: signInProviderCallbackPost
      tags:
      - authentication
      parameters:
      - $ref: '#/components/parameters/SignInProvider'
      requestBody:
        description: OAuth2 provider callback data including authorization code, ID token, and state
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                code:
                  type: string
                  nullable: true
                  description: Authorization code provided by the authentication provider
                id_token:
                  type: string
                  nullable: true
                  description: ID token provided by the authentication provider
                state:
                  type: string
                  description: State parameter to avoid CSRF attacks
                user:
                  type: string
                  nullable: true
                  description: JSON string containing user information (only provided on first authentication with Apple)
                error:
                  type: string
                  nullable: true
                  description: Error message if authentication failed
                error_description:
                  type: string
                  nullable: true
                  description: Detailed error description if authentication failed
                error_uri:
                  type: string
                  nullable: true
                  description: URI with more information about the error
              required:
              - state
              additionalProperties: true
      responses:
        '302':
          description: Redirect to client application after successful authentication
          headers:
            Location:
              $ref: '#/components/headers/RedirectLocation'
          content: {}
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signin/webauthn:
    post:
      summary: Sign in with Webauthn
      description: Initiate a Webauthn sign-in process by sending a challenge to the user's device. The user must have previously registered a Webauthn credential.
      operationId: signInWebauthn
      requestBody:
        description: Optional email address to help identify the user for WebAuthn authentication
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInWebauthnRequest'
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicKeyCredentialRequestOptions'
          description: Challenge sent
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
      tags:
      - authentication
  /signin/webauthn/verify:
    post:
      summary: Verify Webauthn sign-in
      description: Complete the Webauthn sign-in process by verifying the response from the user's device. Returns a session if validation is successful.
      operationId: verifySignInWebauthn
      requestBody:
        description: WebAuthn credential assertion response from the user's authenticator device
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignInWebauthnVerifyRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionPayload'
          description: Sign in successful
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
      tags:
      - authentication
  /signup/email-password:
    post:
      summary: Sign up with email and password
      description: Register a new user account with email and password. Returns a session if email verification is not required, otherwise returns null session.
      operationId: signUpEmailPassword
      tags:
      - authentication
      requestBody:
        description: User registration information including email, password, and optional profile data
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignUpEmailPasswordRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionPayload'
          description: Registration successful. If email verification is required, session will be null.
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
  /signup/webauthn:
    post:
      summary: Sign up with Webauthn
      description: Initiate a Webauthn sign-up process by sending a challenge to the user's device. The user must not have an existing account.
      operationId: signUpWebauthn
      requestBody:
        description: Email address and optional user options for WebAuthn registration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignUpWebauthnRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicKeyCredentialCreationOptions'
          description: Challenge sent
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
      tags:
      - authentication
  /signup/webauthn/verify:
    post:
      summary: Verify Webauthn sign-up
      description: Complete the Webauthn sign-up process by verifying the response from the user's device. Returns a session if validation is successful.
      operationId: verifySignUpWebauthn
      requestBody:
        description: WebAuthn credential creation response and optional user profile information
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignUpWebauthnVerifyRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionPayload'
          description: Sign up successful
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
      tags:
      - authentication
  /user/deanonymize:
    post:
      summary: Deanonymize an anonymous user
      description: Convert an anonymous user to a regular user by adding email and optionally password credentials. A confirmation email will be sent if the server is configured to do so.
      operationId: deanonymizeUser
      tags:
      - authentication
      security:
      - BearerAuth: []
      requestBody:
        description: Authentication method and credentials to convert anonymous user to regular user
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDeanonymizeRequest'
        required: true
      responses:
        '200':
          description: User deanonymized successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OKResponse'
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: An error occurred while processing the request
components:
  schemas:
    SessionPayload:
      type: object
      description: Container for session information
      additionalProperties: false
      properties:
        session:
          $ref: '#/components/schemas/Session'
    UserEntity:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: A human-palatable name for the entity
        displayName:
          type: string
          description: A human-palatable name for the user account, intended only for display
        id:
          type: string
          description: The user handle of the user account entity
      required:
      - name
      - displayName
      - id
    CredentialAssertionResponse:
      type: object
      x-go-type-import:
        name: protocol
        path: github.com/go-webauthn/webauthn/protocol
      x-go-type: protocol.CredentialAssertionResponse
      additionalProperties: false
      properties:
        id:
          type: string
          description: The credential's identifier
        type:
          type: string
          description: The credential type represented by this object
        rawId:
          $ref: '#/components/schemas/URLEncodedBase64'
        clientExtensionResults:
          $ref: '#/components/schemas/AuthenticationExtensionsClientOutputs'
        authenticatorAttachment:
          type: string
          description: The authenticator attachment
        response:
          $ref: '#/components/schemas/AuthenticatorAssertionResponse'
      required:
      - id
      - type
      - rawId
      - response
    URLEncodedBase64:
      type: string
      format: byte
      description: Base64url-encoded binary data
    SignInEmailPasswordResponse:
      type: object
      description: Response for email-password authentication that may include a session or MFA challenge
      additionalProperties: false
      properties:
        session:
          $ref: '#/components/schemas/Session'
        mfa:
          $ref: '#/components/schemas/MFAChallengePayload'
    CredentialParameter:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/CredentialType'
        alg:
          type: integer
          description: The cryptographic algorithm identifier
      required:
      - type
      - alg
    SignInIdTokenRequest:
      type: object
      additionalProperties: false
      properties:
        provider:
          $ref: '#/components/schemas/IdTokenProvider'
        idToken:
          type: string
          description: Apple ID token
        nonce:
          type: string
          description: Nonce used during sign in process
        options:
          $ref: '#/components/schemas/SignUpOptions'
      required:
      - provider
      - idToken
    SignInWebauthnRequest:
      type: object
      additionalProperties: false
      properties:
        email:
          description: A valid email
          example: john.smith@nhost.io
          format: email
          type: string
    UserDeanonymizeRequest:
      type: object
      additionalProperties: false
      properties:
        signInMethod:
          description: Which sign-in method to use
          type: string
          enum:
          - email-password
          - passwordless
        email:
          description: A valid email
          example: john.smith@nhost.io
          format: email
          type: string
        password:
          description: A password of minimum 3 characters
          example: Str0ngPassw#ord-94|%
          minLength: 3
          maxLength: 50
          type: string
        connection:
          deprecated: true
          description: Deprecated, will be ignored
          type: string
        options:
          $ref: '#/components/schemas/SignUpOptions'
      required:
      - signInMethod
      - email
    RelyingPartyEntity:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: A human-palatable name for the entity
        id:
          type: string
          description: A unique identifier for the Relying Party entity, which sets the RP ID
      required:
      - name
      - id
    SignInPasswordlessEmailRequest:
      type: object
      additionalProperties: false
      properties:
        email:
          description: A valid email
          example: john.smith@nhost.io
          format: email
          type: string
        options:
          $ref: '#/components/schemas/SignUpOptions'
      required:
      - email
    IdTokenProvider:
      type: string
      additionalProperties: false
      enum:
      - apple
      - google
    PublicKeyCredentialRequestOptions:
      type: object
      x-go-type-import:
        name: protocol
        path: github.com/go-webauthn/webauthn/protocol
      x-go-type: protocol.PublicKeyCredentialRequestOptions
      additionalProperties: false
      properties:
        challenge:
          $ref: '#/components/schemas/URLEncodedBase64'
        timeout:
          type: integer
          description: A time, in milliseconds, that the caller is willing to wait for the call to complete
        rpId:
          type: string
          description: The RP ID the credential should be scoped to
        allowCredentials:
          type: array
          items:
            $ref: '#/components/schemas/PublicKeyCredentialDescriptor'
          description: A list of CredentialDescriptor objects representing public key credentials acceptable to the caller
        userVerification:
          $ref: '#/components/schemas/UserVerificationRequirement'
        hints:
          type: array
          items:
            $ref: '#/components/schemas/PublicKeyCredentialHints'
          description: Hints to help guide the user through the experience
        extensions:
          $ref: '#/components/schemas/AuthenticationExtensions'
      required:
      - challenge
    SignInWebauthnVerifyRequest:
      type: object
      additionalProperties: false
      properties:
        email:
          description: A valid email. Deprecated, no longer used
          example: john.smith@nhost.io
          format: email
          type: string
          deprecated: true
        credential:
          $ref: '#/components/schemas/CredentialAssertionResponse'
      required:
      - credential
    ConveyancePreference:
      type: string
      enum:
      - none
      - indirect
      - direct
      - enterprise
      default: none
      description: The attestation conveyance preference
    SignInPATRequest:
      type: object
      additionalProperties: false
      properties:
        personalAccessToken:
          description: PAT
          example: 2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24
          pattern: \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b
          type: string
      required:
      - personalAccessToken
    SignInMfaTotpRequest:
      type: object
      additionalProperties: false
      properties:
        ticket:
          type: string
          description: Ticket
          pattern: ^mfaTotp:.*$
        otp:
          type: string
          description: One time password
      required:
      - ticket
      - otp
    OKResponse:
      type: string
      additionalProperties: false
      enum:
      - OK
    CredentialPropertiesOutput:
      type: object
      additionalProperties: false
      description: Credential properties extension output
      properties:
        rk:
          type: boolean
          description: Indicates if the credential is a resident key
    SignInOTPEmailRequest:
      type: object
      additionalProperties: false
      properties:
        email:
          description: A valid email
          example: john.smith@nhost.io
          format: email
          type: string
        options:
          $ref: '#/components/schemas/SignUpOptions'
      required:
      - email
    SignUpWebauthnRequest:
      type: object
      additionalProperties: false
      properties:
        email:
          description: A valid email
          example: john.smith@nhost.io
          format: email
          type: string
        options:
          $ref: '#/components/schemas/SignUpOptions'
      required:
      - email
    AttestationFormat:
      type: string
      enum:
      - packed
      - tpm
      - android-key
      - android-safetynet
      - fido-u2f
      - apple
      - none
      description: The attestation statement format
    MFAChallengePayload:
      type: object
      description: Challenge payload for multi-factor authentication
      additionalProperties: false
      properties:
        ticket:
          type: string
          description: Ticket to use when completing the MFA challenge
          example: mfaTotp:abc123def456
      required:
      - ticket
    AuthenticatorAttachment:
      type: string
      enum:
      - platform
      - cross-platform
      description: The authenticator attachment modality
    CredentialCreationResponse:
      type: object
      additionalProperties: false
      x-go-type-import:
        name: protocol
        path: github.com/go-webauthn/webauthn/protocol
      x-go-type: protocol.CredentialCreationResponse
      properties:
        id:
          type: string
          description: The credential's identifier
        type:
          type: string
          description: The credential type represented by this object
        rawId:
          $ref: '#/components/schemas/URLEncodedBase64'
        clientExtensionResults:
          $ref: '#/components/schemas/AuthenticationExtensionsClientOutputs'
        authenticatorAttachment:
          type: string
          description: The authenticator attachment
        response:
          $ref: '#/components/schemas/AuthenticatorAttestationResponse'
      required:
      - id
      - type
      - rawId
      - response
    SignInPasswordlessSmsOtpResponse:
      type: object
      additionalProperties: false
      properties:
        session:
          $ref: '#/components/schemas/Session'
        mfa:
          $ref: '#/components/schemas/MFAChallengePayload'
    SignUpOptions:
      type: object
      additionalProperties: false
      properties:
        allowedRoles:
          example:
          - me
          - user
          type: array
          items:
            type: string
        defaultRole:
          example: user
          type: string
        displayName:
          example: John Smith
          type: string
          pattern: ^[\p{L}\p{N}\p{S} ,.'-]+$
          maxLength: 32
        locale:
          description: A two-characters locale
          example: en
          maxLength: 2
          minLength: 2
          type: string
        metadata:
          type: object
          additionalProperties: true
          example:
            firstName: John
            lastName: Smith
          properties: {}
        redirectTo:
          type: string
          format: uri
          example: https://my-app.com/catch-redirection
    SignInEmailPasswordRequest:
      type: object
      description: Request to authenticate using email and password
      additionalProperties: false
      properties:
        email:
          description: User's email address
          example: john.smith@nhost.io
          format: email
          type: string
        password:
          description: User's password
          example: Str0ngPassw#ord-94|%
          minLength: 3
          maxLength: 50
          type: string
      required:
      - email
      - password
    AuthenticatorAttestationResponse:
      type: object
      additionalProperties: false
      properties:
        clientDataJSON:
          $ref: '#/components/schemas/URLEncodedBase64'
        transports:
          type: array
          items:
            type: string
          description: The authenticator transports
        authenticatorData:
          $ref: '#/components/schemas/URLEncodedBase64'
        publicKey:
          $ref: '#/components/schemas/URLEncodedBase64'
        publicKeyAlgorithm:
          type: integer
          format: int64
          description: The public key algorithm identifier
        attestationObject:
          $ref: '#/components/schemas/URLEncodedBase64'
      required:
      - clientDataJSON
      - attestationObject
    AuthenticatorSelection:
      type: object
      additionalProperties: false
      properties:
        authenticatorAttachment:
          $ref: '#/components/schemas/AuthenticatorAttachment'
        requireResidentKey:
          type: boolean
          description: Whether the authenticator must create a client-side-resident public key credential source
        residentKey:
          $ref: '#/components/schemas/ResidentKeyRequirement'
        userVerification:
          $ref: '#/components/schemas/UserVerificationRequirement'
    AuthenticationExtensionsClientOutputs:
      type: object
      additionalProperties: true
      description: Map of extension outputs from the client
      properties:
        appid:
          type: boolean
          description: Application identifier extension output
        credProps:
          $ref: '#/components/schemas/CredentialPropertiesOutput'
        hmacCreateSecret:
          type: boolean
          description: HMAC secret extension output
    CredentialType:
      type: string
      enum:
      - public-key
      description: The valid credential types
    SignInAnonymousRequest:
      type: object
      additionalProperties: false
      properties:
        displayName:
          example: John Smith
          type: string
        locale:
          description: A two-characters locale
          example: en
          maxLength: 2
          minLength: 2
          type: string
        metadata:
          type: object
          additionalProperties: true
          example:
            firstName: John
            lastName: Smith
          properties: {}
    SignInOTPEmailVerifyResponse:
      type: object
      additionalProperties: false
      properties:
        session:
          $ref: '#/components/schemas/Session'
    User:
      type: object
      description: User profile and account information
      additionalProperties: false
      properties:
        avatarUrl:
          type: string
          description: URL to the user's profile picture
          example: https://myapp.com/avatars/user123.jpg
        createdAt:
          format: date-time
          type: string
          description: Timestamp when the user account was created
          example: '2023-01-15T12:34:56Z'
        defaultRole:
          example: user
          type: string
          description: Default authorization role for the user
        displayName:
          example: John Smith
          type: string
          description: User's display name
        email:
          description: User's email address
          example: john.smith@nhost.io
          format: email
          type: string
        emailVerified:
          type: boolean
          description: Whether the user's email has been verified
          example: true
        id:
          description: Unique identifier for the user
          example: 2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24
          pattern: \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b
          type: string
        isAnonymous:
          type: boolean
          description: Whether this is an anonymous user account
          example: false
        locale:
          description: User's preferred locale (language code)
          example: en
          maxLength: 2
          minLength: 2
          type: string
        metadata:
          type: object
          additionalProperties: true
          description: Custom metadata associated with the user
          example:
            firstName: John
            lastName: Smith
          properties: {}
        phoneNumber:
          type: string
          description: User's phone number
          example: '+12025550123'
        phoneNumberVerified:
          type: boolean
          description: Whether the user's phone number has been verified
          example: false
        roles:
          example:
          - user
          - customer
          type: array
          description: List of roles assigned to the user
          items:
            type: string
        activeMfaType:
          type: string
          description: Active MFA type for the user
          nullable: true
      required:
      - avatarUrl
      - createdAt
      - defaultRole
      - displayName
      - emailVerified
      - id
      - isAnonymous
      - locale
      - metadata
      - phoneNumberVerified
      - roles
    SignUpWebauthnVerifyRequest:
      type: object
      additionalProperties: false
      properties:
        credential:
          $ref: '#/components/schemas/CredentialCreationResponse'
        options:
          $ref: '#/components/schemas/SignUpOptions'
        nickname:
          description: Nickname for the security key
          type: string
      required:
      - credential
    ErrorResponse:
      type: object
      description: Standardized error response
      additionalProperties: false
      properties:
        status:
          description: HTTP status error code
          type: integer
          example: 400
        message:
          description: Human-friendly error message
          type: string
          example: Invalid email format
        error:
          description: Error code identifying the specific application error
          type: string
          enum:
          - default-role-must-be-in-allowed-roles
          - disabled-endpoint
          - disabled-user
          - email-already-in-use
          - email-already-verified
          - forbidden-anonymous
          - internal-server-error
          - invalid-email-password
          - invalid-request
          - locale-not-allowed
          - password-too-short
          - password-in-hibp-database
          - redirectTo-not-allowed
          - role-not-allowed
          - signup-disabled
          - unverified-user
          - user-not-anonymous
          - invalid-pat
          - invalid-refresh-token
          - invalid-ticket
          - disabled-mfa-totp
          - no-totp-secret
          - invalid-totp
          - mfa-type-not-found
          - totp-already-active
          - invalid-state
          - oauth-token-echange-failed
          - oauth-profile-fetch-failed
          - oauth-provider-error
          - invalid-otp
          - cannot-send-sms
      required:
      - status
      - message
      - error
    Session:
      type: object
      description: User authentication session containing tokens and user information
      additionalProperties: false
      properties:
        accessToken:
          type: string
          description: JWT token for authenticating API requests
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        accessTokenExpiresIn:
          type: integer
          format: int64
          description: Expiration time of the access token in seconds
          example: 900
        refreshTokenId:
          description: Identifier for the refresh token
          example: 2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24
          pattern: \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b
          type: string
        refreshToken:
          description: Token used to refresh the access token
          example: 2c35b6f3-c4b9-48e3-978a-d4d0f1d42e24
          pattern: \b[0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12}\b
          type: string
        user:
          $ref: '#/components/schemas/User'
      required:
      - accessToken
      - accessTokenExpiresIn
      - refreshToken
      - refreshTokenId
    SignInPasswordlessSmsOtpRequest:
      type: object
      additionalProperties: false
      properties:
        phoneNumber:
          description: Phone number of the user
          example: '+123456789'
          type: string
        otp:
          type: string
          description: One-time password received by SMS
      required:
      - phoneNumber
      - otp
    PublicKeyCredentialDescriptor:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/CredentialType'
        id:
          $ref: '#/components/schemas/URLEncodedBase64'
        transports:
          type: array
          items:
            $ref: '#/components/schemas/AuthenticatorTransport'
          description: The authenticator transports that can be used
      required:
      - type
      - id
    ResidentKeyRequirement:
      type: string
      enum:
      - discouraged
      - preferred
      - required
      default: discouraged
      description: The resident key requirement
    PublicKeyCredentialCreationOptions:
      type: object
      x-go-type-import:
        name: protocol
        path: github.com/go-webauthn/webauthn/protocol
      x-go-type: protocol.PublicKeyCredentialCreationOptions
      additionalProperties: false
      properties:
        rp:
          $ref: '#/components/schemas/RelyingPartyEntity'
        user:
          $ref: '#/components/schemas/UserEntity'
        challenge:
          $ref: '#/components/schemas/URLEncodedBase64'
        pubKeyCredParams:
          type: array
          items:
            $ref: '#/components/schemas/CredentialParameter'
          description: The desired credential types and their respective cryptographic parameters
        timeout:
          type: integer
          description: A time, in milliseconds, that the caller is willing to wait for the call to complete
        excludeCredentials:
          type: array
          items:
            $ref: '#/components/schemas/PublicKeyCredentialDescriptor'
          description: A list of PublicKeyCredentialDescriptor objects representing public key credentials that are not acceptable to the caller
        authenticatorSelection:
          $ref: '#/components/schemas/AuthenticatorSelection'
        hints:
          type: array
          items:
            $ref: '#/components/schemas/PublicKeyCredentialHints'
          description: Hints to help guide the user through the experience
        attestation:
          $ref: '#/components/schemas/ConveyancePreference'
        attestationFormats:
          type: array
          items:
            $ref: '#/components/schemas/AttestationFormat'
          description: The preferred attestation statement formats
        extensions:
          $ref: '#/components/schemas/AuthenticationExtensions'
      required:
      - rp
      - user
      - challenge
      - pubKeyCredParams
    SignInPasswordlessSmsRequest:
      type: object
      additionalProperties: false
      properties:
        phoneNumber:
          description: Phone number of the user
          example: '+123456789'
          type: string
        options:
          $ref: '#/components/schemas/SignUpOptions'
      required:
      - phoneNumber
    SignUpEmailPasswordRequest:
      type: object
      description: Request to register a new user with email and password
      additionalProperties: false
      properties:
        email:
          description: Email address for the new user account
          example: john.smith@nhost.io
          format: email
          type: string
        password:
          description: Password for the new user account
          example: Str0ngPassw#ord-94|%
          minLength: 3
          maxLength: 50
          type: string
        options:
          $ref: '#/components/schemas/SignUpOptions'
      required:
      - email
      - password
    AuthenticatorTransport:
      type: string
      enum:
      - usb
      - nfc
      - ble
      - smart-card
      - hybrid
      - internal
      description: The authenticator transports that can be used
    UserVerificationRequirement:
      type: string
      enum:
      - required
      - preferred
      - discouraged
      default: preferred
      description: A requirement for user verification for the operation
    AuthenticatorAssertionResponse:
      type: object
      additionalProperties: false
      properties:
        clientDataJSON:
          type: string
          description: Base64url encoded client data JSON
        authenticatorData:
          type: string
          description: Base64url encoded authenticator data
        signature:
          type: string
          description: Base64url encoded assertion signature
        userHandle:
          type: string
          nullable: true
          description: Base64url encoded user handle
      required:
      - clientDataJSON
      - authenticatorData
      - signature
    AuthenticationExtensions:
      type: object
      additionalProperties: true
      description: Additional parameters requesting additional processing by the client and authenticator
    SignInOTPEmailVerifyRequest:
      type: object
      additionalProperties: false
      properties:
        otp:
          type: string
          description: One time password
        email:
          description: A valid email
          example: john.smith@nhost.io
          format: email
          type: string
      required:
      - otp
      - email
    PublicKeyCredentialHints:
      type: string
      enum:
      - security-key
      - client-device
      - hybrid
      description: Hints to help guide the user through the experience
  headers:
    RedirectLocation:
      description: URL to redirect to
      schema:
        type: string
        format: uri
      required: true
  parameters:
    SignInProvider:
      in: path
      name: provider
      required: true
      description: The name of the social provider
      schema:
        type: string
        enum:
        - apple
        - github
        - google
        - linkedin
        - discord
        - spotify
        - twitch
        - gitlab
        - bitbucket
        - workos
        - azuread
        - entraid
        - strava
        - facebook
        - windowslive
        - twitter
      deprecated: true
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication with JWT access token. Used to authenticate requests to protected endpoints.
    BearerAuthElevated:
      type: http
      scheme: bearer
      description: Bearer authentication that requires elevated permissions. Used for sensitive operations that may require additional security measures such as recent authentication. For details see https://docs.nhost.io/guides/auth/elevated-permissions