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

# Get 2FA code

> Retrieves the current two-factor authentication (2FA) code for a single
vault entry, identified by permissioned_user_id and domain.

Choosing the method:
- Entry with one 2FA method: that method is used. `method` is optional.
- Entry with several 2FA methods: pass `method`, otherwise 400.
- `field`: returns the code of a `Totp` additional field instead of the
  built-in authenticator seed.

Behavior depends on the method:
- **Authenticator (TOTP):** a fresh time-based code is generated from the
  stored secret (or the `Totp` additional field named by `field`). The
  response includes `expires_in_seconds`.
- **Email:** returns the most recently received code, provided it arrived
  within the freshness window (otherwise 404). The response includes
  `received_at`.
- **SMS and magic link:** not supported via this endpoint (409). SMS codes
  arrive at a single shared phone number with no per-credential marker (and
  the message body often has no service name), so a code cannot be reliably
  attributed to the requested credential. Use email or authenticator.

The code is returned with `Cache-Control: no-store` and is never logged.

> **Note:**
>
> * Both `permissioned_user_id` and `domain` are required.
> * If the entry has more than one 2FA method, pass `method` (`AUTHENTICATOR`, `EMAIL`, `SMS` or `MAGIC_LINK`); otherwise a `400` is returned. A `method` the entry does not have returns `409`.
> * Pass `field` with the name of a `Totp` [additional field](https://docs.cloudcruise.com/concepts/vault.md#additional-fields) to get that field's current code. `field` implies `AUTHENTICATOR`; combining it with another `method` returns `400`. A missing field returns `404`; a field that is not `Totp` returns `400`.
> * For authenticator (TOTP) credentials, a fresh code is generated and the response includes `expires_in_seconds`.
> * For email credentials, the most recently received code is returned if it arrived within the freshness window; otherwise a `404` is returned. The response includes `received_at`.
> * SMS and magic-link credentials are not supported on this endpoint (`409`). SMS codes arrive at a single shared phone number with no per-credential marker (and the message body often has no service name), so they can't be reliably attributed to the requested credential — use email or authenticator.
> * Codes are returned with `Cache-Control: no-store`. Do not log or cache them.


## OpenAPI

````yaml vault-api/vault-api.yaml get /vault/tfa-code
openapi: 3.1.0
info:
  title: CloudCruise Vault API
  version: 0.1.0
  description: Endpoints for managing vault entries.
servers:
  - url: https://api.cloudcruise.com
    description: CloudCruise Platform Production API Server
security:
  - AuthScheme: []
paths:
  /vault/tfa-code:
    get:
      summary: Get 2FA code
      description: >-
        Retrieves the current two-factor authentication (2FA) code for a single

        vault entry, identified by permissioned_user_id and domain.


        Choosing the method:

        - Entry with one 2FA method: that method is used. `method` is optional.

        - Entry with several 2FA methods: pass `method`, otherwise 400.

        - `field`: returns the code of a `Totp` additional field instead of the
          built-in authenticator seed.

        Behavior depends on the method:

        - **Authenticator (TOTP):** a fresh time-based code is generated from
        the
          stored secret (or the `Totp` additional field named by `field`). The
          response includes `expires_in_seconds`.
        - **Email:** returns the most recently received code, provided it
        arrived
          within the freshness window (otherwise 404). The response includes
          `received_at`.
        - **SMS and magic link:** not supported via this endpoint (409). SMS
        codes
          arrive at a single shared phone number with no per-credential marker (and
          the message body often has no service name), so a code cannot be reliably
          attributed to the requested credential. Use email or authenticator.

        The code is returned with `Cache-Control: no-store` and is never logged.
      operationId: get_vault_tfa_code
      parameters:
        - name: permissioned_user_id
          in: query
          required: true
          schema:
            type: string
            description: Unique identifier for the vault entry.
        - name: domain
          in: query
          required: true
          schema:
            type: string
            description: Target domain of the vault entry.
        - name: method
          in: query
          required: false
          schema:
            type: string
            enum:
              - AUTHENTICATOR
              - EMAIL
              - SMS
              - MAGIC_LINK
            description: >-
              2FA method to read. Required when the entry has more than one
              method. Must be one of the entry's `tfa_methods`.
        - name: field
          in: query
          required: false
          schema:
            type: string
            description: >-
              Name of a `Totp` additional field on the entry. Returns that
              field's current code (`type` is `authenticator`). Implies
              `method=AUTHENTICATOR`.
      responses:
        '200':
          description: 2FA code successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultTfaCode'
        '400':
          description: >-
            Invalid request. Possible causes:

            - Missing authentication headers

            - permissioned_user_id / domain not provided

            - The entry has more than one 2FA method and `method` is not
            provided

            - `field` combined with a `method` other than `AUTHENTICATOR`

            - The additional field named by `field` is not of type `Totp`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 400
                message: Both permissioned_user_id and domain are required
                error: Bad Request
        '403':
          description: >-
            Another workspace shares the same (permissioned_user_id, domain) for
            an

            email credential, so the cached code can't be safely attributed to
            this

            tenant and is withheld.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 403
                message: >-
                  Verification email preview is not available for this
                  credential. Contact support.
                error: Forbidden
        '404':
          description: >-
            No credential found, no additional field named by `field`, or no
            recent

            email/SMS code is available within the freshness window.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 404
                message: No recent code available
                error: Not Found
        '409':
          description: |-
            Possible causes:
            - `method` is not one of the entry's `tfa_methods`
            - Code retrieval is not supported for the method (SMS or magic link)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 409
                message: >-
                  SMS code retrieval requires a dedicated phone number for this
                  workspace
                error: Conflict
        '422':
          description: The stored authenticator secret is invalid (not base32-encoded).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                statusCode: 422
                message: Invalid TFA secret
                error: Unprocessable Entity
components:
  schemas:
    VaultTfaCode:
      type: object
      description: |-
        The current 2FA code for a vault entry. `expires_in_seconds` is present
        for authenticator (TOTP) codes; `received_at` is present for email/SMS
        codes.
      properties:
        type:
          type: string
          enum:
            - authenticator
            - email
          description: The 2FA method this code was produced for.
        code:
          type: string
          description: The one-time code.
          example: '123456'
        expires_in_seconds:
          type: integer
          description: Seconds until the authenticator code rotates (authenticator only).
          example: 23
        received_at:
          type: string
          format: date-time
          description: When the email/SMS code was received (email/SMS only).
      required:
        - type
        - code
    ErrorResponse:
      type: object
      description: Error response returned when a request fails
      properties:
        statusCode:
          type: integer
          description: HTTP status code
        message:
          type: string
          description: Human-readable error message
        error:
          type: string
          description: HTTP status text (e.g., "Not Found", "Conflict")
      required:
        - statusCode
        - message
  securitySchemes:
    AuthScheme:
      type: apiKey
      name: cc-key
      in: header
      description: >-
        API key-based authentication. Provide your CloudCruise API key in the
        cc-key header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.