# Create a credential invitation.

Creates a pending invitation in the organization and environment selected by the authenticated service user and required headers.
The response contains the only current plaintext code. DeepCredentials does not email the code or return a redemption URL in the B2B flow. Your system owns code delivery and the recipient experience. Exchange the recipient's email and code through `POST /api/v1/public/credential-invitations/redeem`; where and how your system exposes that flow is up to you.
Only one pending invitation may exist for the same organization, environment, credential definition, and normalized email address. `reference_id` is correlation metadata only; it does not make this operation idempotent or unique.

Endpoint: POST /b2b/v1/credential-invitations
Version: 1.0.0
Security: BearerAuth

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

  - `credential_definition_id` (string, required)
    Credential definition to issue after redemption. Configure it in the portal before making runtime B2B calls.

  - `email` (string, required)
    Recipient email used together with the code by the public redemption endpoint. It is trimmed and normalized to lowercase when stored. DeepCredentials does not email it in this B2B flow.

  - `claims` (object, required)
    Claim values for the eventual credential. Keys and JSON value types must match the credential definition, all mandatory claims must be present, and the serialized payload must not exceed 6 MB. Invitation responses do not return these values; retain them in your own durable request record when lost-response recovery matters.

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

  - `invitation_ttl_seconds` (integer, required)
    Positive lifetime of the invitation code in seconds.

  - `offer_validity_seconds` (integer)
    Optional positive lifetime, in seconds, of the credential offer created after redemption.

  - `validity_seconds` (integer)
    Optional eventual credential lifetime in seconds. Omit to use the credential definition default. Allowed range is 60 seconds through 10 years. Invitation responses do not return this value; retain it in your own durable request record when lost-response recovery matters.

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

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

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