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: "[email protected]"
    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)"
  - name: security
    description: "Security-related operations including Personal Access Tokens, WebAuthn management, account elevation, and account linking"
  - name: session
    description: "Session management operations including token refresh, verification, and sign-out"
  - name: user
    description: "User profile and account management operations including email/password changes, MFA configuration, and profile updates"
  - name: system
    description: "System operations including health checks, service version, and public key endpoints"
  - name: verification
    description: "Email and ticket verification operations for confirming user actions"
  - name: excludeme
    description: "These operations are not intended to be used directly by clients and should be excluded from client SDKs"

paths:
  /.well-known/jwks.json:
    get:
      summary: Get public keys for JWT verification in JWK Set format
      description: Retrieve the JSON Web Key Set (JWKS) containing public keys used to verify JWT signatures. This endpoint is used by clients to validate access tokens.
      operationId: getJWKs
      tags:
        - system
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JWKSet"
          description: >-
            The public keys in JWK Set format
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: "An error occurred while processing the request"

  /elevate/webauthn:
    post:
      summary: Elevate access for an already signed in user using FIDO2 Webauthn
      description: Generate a Webauthn challenge for elevating user permissions
      operationId: elevateWebauthn
      tags:
        - security
      security:
        - BearerAuth: []
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PublicKeyCredentialRequestOptions"
          description: >-
            Challenge sent for elevation
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: An error occurred while processing the request

  /elevate/webauthn/verify:
    post:
      summary: Verify FIDO2 Webauthn authentication using public-key cryptography for elevation
      description: Complete Webauthn elevation by verifying the authentication response
      operationId: verifyElevateWebauthn
      tags:
        - security
      security:
        - BearerAuth: []
      requestBody:
        description: WebAuthn credential assertion response for elevation verification
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignInWebauthnVerifyRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SessionPayload"
          description: >-
            Elevated successfully
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: An error occurred while processing the request

  /healthz:
    get:
      summary: Health check (GET)
      description: Verify if the authentication service is operational using GET method
      operationId: healthCheckGet
      tags:
        - system
      responses:
        "200":
          description: "Service is healthy and operational"
          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"

    head:
      summary: Health check (HEAD)
      description: Verify if the authentication service is operational using HEAD method
      operationId: healthCheckHead
      tags:
        - system
      responses:
        "200":
          description: "Service is healthy and operational"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: "An error occurred while processing the request"

  /link/idtoken:
    post:
      summary: Link a user account with the provider's account using an id token
      description: Link the authenticated user's account with an external OAuth provider account using an ID token. Requires elevated permissions.
      operationId: linkIdToken
      tags:
        - security
      security:
        - BearerAuthElevated: []
      requestBody:
        description: ID token and provider information for account linking
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LinkIdTokenRequest"
        required: true
      responses:
        "200":
          description: >-
            Identity linked 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"

  /mfa/totp/generate:
    get:
      summary: Generate TOTP secret
      description: Generate a Time-based One-Time Password (TOTP) secret for setting up multi-factor authentication
      operationId: changeUserMfa
      tags:
        - user
      security:
        - BearerAuth: []
      responses:
        "200":
          description: "TOTP secret successfully generated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TotpGenerateResponse"
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: "An error occurred while processing the request"

  /pat:
    post:
      summary: Create a Personal Access Token (PAT)
      description: Generate a new Personal Access Token for programmatic API access. PATs are long-lived tokens that can be used instead of regular authentication for automated systems. Requires elevated permissions.
      operationId: createPAT
      tags:
        - security
      security:
        - BearerAuthElevated: []
      requestBody:
        description: Personal Access Token creation request with expiration and metadata
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePATRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreatePATResponse"
          description: >-
            Successfully created a Personal Access Token
        default:
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: "An error occurred while processing the request"

  /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
        - excludeme
      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
        - excludeme
      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

  /signout:
    post:
      summary: Sign out
      description: End the current user session by invalidating refresh tokens. Optionally sign out from all devices.
      operationId: signOut
      tags:
        - session
      security:
        - BearerAuth: []
        - {}
      requestBody:
        description: Sign-out options including refresh token and whether to sign out from all devices
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SignOutRequest"
      responses:
        "200":
          description: "Successfully signed out"
          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"

  /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
        - verification

  /token:
    post:
      summary: Refresh access token
      description: Generate a new JWT access token using a valid refresh token. The refresh token used will be revoked and a new one will be issued.
      operationId: refreshToken
      tags:
        - session
      requestBody:
        description: Refresh token to exchange for a new access token
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RefreshTokenRequest"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Session"
          desc

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