Nhost authentication API

openapi: 3.2.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
                  - 'null'
                  description: Authorization code provided by the authentication provider
                id_token:
                  type:
                  - string
                  - 'null'
                  description: ID token provided by the authentication provider
                state:
                  type: string
                  description: State parameter to avoid CSRF attacks
                user:
                  type:
                  - string
                  - 'null'
                  description: JSON string containing user information (only provided on first authentication with Apple)
                error:
                  type:
                  - string
                  - 'null'
                  description: Error message if authentication failed
                error_description:
                  type:
                  - string
                  - 'null'
                  description: Detailed error description if authentication failed
                error_uri:
                  type:
                  - string
                  - 'null'
                  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:
    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
    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
    CredentialPropertiesOutput:
      type: object
      additionalProperties: false
      description: Credential properties extension output
      properties:
        rk:
          type: boolean
          description: Indicates if the credential is a resident key
    CredentialParameter:
      type: object
      additionalProperties: false
      properties:
        type:
          $ref: '#/components/schemas/CredentialType'
        alg:
          type: integer
          description: The cryptographic algorithm identifier
      required:
      - type
      - alg
    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
    AuthenticatorAttachment:
      type: string
      enum:
      - platform
      - cross-platform
      description: The authenticator attachment modality
    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
    SignInOTPEmailVerifyResponse:
      type: object
      additionalProperties: false
      properties:
        session:
          $ref: '#/components/schemas/Session'
    AttestationFormat:
      type: string
      enum:
      - packed
      - tpm
      - android-key
      - android-safetynet
      - fido-u2f
      - apple
      - none
      description: The attestation statement format
    SignInPasswordlessSmsOtpResponse:
      type: object
      additionalProperties: false
      properties:
        session:
          $ref: '#/components/schemas/Session'
        mfa:
          $ref: '#/components/schemas/MFAChallengePayload'
    IdTokenProvider:
      type: string
      additionalProperties: false
      enum:
      - apple
      - google
    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
    UserVerificationRequirement:
      type: string
      enum:
      - required
      - preferred
      - discouraged
      default: preferred
      description: A requirement for user verification for the operation
    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'
    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'
          d

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nhost/refs/heads/main/openapi/nhost-authentication-api-openapi.yml