Nhost authentication API

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:
 

# --- 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