# Rotate a credential invitation code.

Replaces the code of a pending invitation, resets failed attempts, and sets a new expiry from the requested TTL.

Rotation is deliberately non-idempotent: every successful call invalidates the previous code and returns the only current plaintext code. DeepCredentials does not email the replacement. If a rotate response is lost, rotate again until your system receives a response, then deliver that returned code.

Endpoint: POST /b2b/v1/credential-invitations/{invitationId}/rotate-code
Version: 1.0.0
Security: BearerAuth

## Security:

  - `BearerAuth` (unknown)
    http bearer JWT

## Path parameters:

  - `invitationId` (string, required)
    Credential invitation ID.

## Header parameters:

  - `X-Org-Id` (string, required)
    Organization the call is acting on. The authenticated service user must be a member of this organization in DeepAdmin; otherwise the request returns 404.

  - `X-Environment` (string, required)
    Environment the call is scoped to. Invitation resources are isolated per environment.

## Request fields (application/json):

  - `invitation_ttl_seconds` (integer, required)
    Positive lifetime, in seconds, applied from the successful rotation time.

## Response 200:

  - `200` (unknown)
    Code rotated. The caller owns delivery of the replacement code.

## Response 200 fields (application/json):

  - `invitation_id` (string, required)
    Credential invitation ID.

  - `environment` (string, required)
    Environment selected by `X-Environment` when the invitation was created.
    Enum: "beta", "production"

  - `credential_definition_id` (string, required)
    Credential definition used for the eventual offer.

  - `credential_definition_name` (string, required)
    Credential definition name captured when the invitation was created.

  - `email` (string, required)
    Normalized recipient email required for public redemption.

  - `code_last4` (string, required)
    Last four normalized code characters for support and delivery confirmation. This is not a redeemable code.

  - `status` (string, required)
    Current invitation lifecycle state.
    Enum: "pending", "redeemed", "expired", "revoked"

  - `reference_id` (string)
    Optional correlation identifier from your system; echoed on the resource.

  - `offer_validity_seconds` (integer)
    Configured lifetime of the offer created after redemption, when supplied at creation.

  - `redeemed_offer_id` (string)
    Offer created by a successful redemption. Present only after redemption.

  - `expires_at` (string, required)
    Invitation-code expiry timestamp in RFC 3339 UTC.

  - `redeemed_at` (string)
    Successful redemption timestamp in RFC 3339 UTC.

  - `revoked_at` (string)
    Revocation timestamp in RFC 3339 UTC.

  - `created_at` (string, required)
    Creation timestamp in RFC 3339 UTC.

  - `archived_at` (string)
    When an operator put this invitation away in the portal's archive, if they did. A filing decision in the portal's lists; nothing about the invitation changes with it, and it is absent while the invitation is not archived.

  - `code` (string, required)
    One-time plaintext invitation code. Returned only by create and rotate; the caller owns secure delivery.

## Response 400:

  - `400` (unknown)
    The request is invalid (`invalid_argument`), or the invitation is no longer pending (`failed_precondition`). A prior successful rotation does not block another rotation while the invitation remains pending.

## Response 400 fields (application/json):

  - `code` (string, required)
    Machine-readable error code.

  - `message` (string, required)
    Human-readable error description.

  - `details` (object)
    Optional structured data with additional context.

## Response 401:

  - `401` (unknown)
    The Bearer token is missing, invalid, or expired (`unauthenticated`).

## Response 401 fields (application/json):

  - `code` (string, required)
    Machine-readable error code.

  - `message` (string, required)
    Human-readable error description.

  - `details` (object)
    Optional structured data with additional context.

## Response 403:

  - `403` (unknown)
    The authenticated caller is not authorized for this operation (`permission_denied`). The `deepcredentials.issue` scope guard is wired but currently disabled as described above; this response may still come from another authorization gate.

## Response 403 fields (application/json):

  - `code` (string, required)
    Machine-readable error code.

  - `message` (string, required)
    Human-readable error description.

  - `details` (object)
    Optional structured data with additional context.

## Response 404:

  - `404` (unknown)
    The invitation does not exist within the authenticated organization and environment (`not_found`).

## Response 404 fields (application/json):

  - `code` (string, required)
    Machine-readable error code.

  - `message` (string, required)
    Human-readable error description.

  - `details` (object)
    Optional structured data with additional context.

## Response 500:

  - `500` (unknown)
    Unexpected server failure (`internal`).

## Response 500 fields (application/json):

  - `code` (string, required)
    Machine-readable error code.

  - `message` (string, required)
    Human-readable error description.

  - `details` (object)
    Optional structured data with additional context.

## Response 400 examples:

  - `Invalid invitation TTL` (unknown)

  - `Invitation cannot be rotated` (unknown)