> ## Documentation Index
> Fetch the complete documentation index at: https://docs.portalhq.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate a TOTP code

> Completes a sign-in that requires two-factor authentication by verifying
the six-digit code from the user's authenticator app, and returns the
Client Session Token.

This endpoint needs two credentials: the `x-portal-auth-environment-id`
header, and the `userJwt` from the magic link or OAuth validation
response sent as a Bearer token. The `userJwt` may also be passed in the
request body instead of the `Authorization` header.

On the user's first successful verification, enrollment is completed and
subsequent sign-ins no longer return a `totpLink`.




## OpenAPI

````yaml /openapi/authentication-api.yaml post /totps/validations
openapi: 3.1.0
info:
  title: Portal Authentication API
  version: '3.0'
  description: |
    The Portal Authentication API signs in your end users with an email magic
    link, Google, or Apple. A completed sign-in returns a Client Session Token
    that your app uses to create and operate the user's wallet.

    ## Base URL
    `https://api.portalhq.io/api/v3/auth`

    ## Authentication
    These endpoints do not use a Portal API Key or a Client Session Token.
    Identify your environment with the `x-portal-auth-environment-id` header,
    set to the Auth Environment ID shown in the Portal dashboard under
    **Authentication > Configure**.

    Requests are rejected with `401` if the header is missing, if it does not
    match an environment, or if authentication is not enabled for that
    environment.

    ## Response format
    Successful responses are wrapped in a `data` object, alongside a `metadata`
    field that is `null` for every endpoint in this API:

    ```json
    { "data": { "sent": true }, "metadata": null }
    ```

    ## Error responses
    Every authentication failure returns the same generic `401` body, with no
    indication of which check failed. This is deliberate, so a caller cannot
    distinguish an expired token from a forged one. Treat any `401` as "start
    the sign-in flow again".
servers:
  - url: https://api.portalhq.io/api/v3/auth
    description: Production
security:
  - authEnvironmentId: []
tags:
  - name: Auth Methods
    description: Discover which sign-in methods an environment has enabled
  - name: Magic Links
    description: Send and validate email magic links
  - name: OAuth
    description: Sign in with Google or Apple
  - name: Two-Factor Authentication
    description: Validate a time-based one-time password (TOTP) code
paths:
  /totps/validations:
    post:
      tags:
        - Two-Factor Authentication
      summary: Validate a TOTP code
      description: |
        Completes a sign-in that requires two-factor authentication by verifying
        the six-digit code from the user's authenticator app, and returns the
        Client Session Token.

        This endpoint needs two credentials: the `x-portal-auth-environment-id`
        header, and the `userJwt` from the magic link or OAuth validation
        response sent as a Bearer token. The `userJwt` may also be passed in the
        request body instead of the `Authorization` header.

        On the user's first successful verification, enrollment is completed and
        subsequent sign-ins no longer return a `totpLink`.
      operationId: validateTotp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateTotpRequest'
            example:
              code: '123456'
      responses:
        '200':
          description: TOTP code validated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateTotpResponse'
              example:
                data:
                  clientSessionToken: b7c1f0a2-3d4e-5f60-8a91-2b3c4d5e6f70
                metadata: null
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          description: |
            Unauthorized. Returned when the `userJwt` is missing, invalid, or
            already used, when the code is incorrect, or when the user has no
            TOTP secret enrolled.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Unauthorized
      security:
        - authEnvironmentId: []
          userJwt: []
components:
  schemas:
    ValidateTotpRequest:
      type: object
      required:
        - code
      properties:
        code:
          type: string
          description: The six-digit code from the user's authenticator app.
        userJwt:
          type: string
          description: |
            The `userJwt` for this sign-in. Optional, and only needed if you are
            not sending it as a Bearer token in the `Authorization` header.
    ValidateTotpResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            clientSessionToken:
              type: string
              description: The Client Session Token for this user's client.
        metadata:
          type:
            - object
            - 'null'
          description: Always `null` for this endpoint.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
        details:
          type: object
          description: Additional context about the failure, when available
        code:
          type: string
          description: Machine-readable error code, when available
  responses:
    BadRequest:
      description: Bad request. A required field is missing or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: email must be a valid email address.
  securitySchemes:
    authEnvironmentId:
      type: apiKey
      in: header
      name: x-portal-auth-environment-id
      description: |
        The Auth Environment ID for the environment you are authenticating
        against. Find it in the Portal dashboard under
        **Authentication > Configure**.
    userJwt:
      type: http
      scheme: bearer
      description: |
        The `userJwt` returned by a magic link or OAuth validation when the
        environment requires two-factor authentication. Single use.

````