Skip to content
Trustaige Docs
API reference

Customer credentials

Offer a credential

post /o/{shortId}/api/credentials/offers

Create a subject for a new customer and a link that claims their credential, or re-offer to a customer you already hold. Nothing about the person goes in the request: names and addresses stay in your database.

Authentication

A client token (Authorization: Bearer …) from POST /oauth2/token with the scope offers:write .

Path parameters

  • shortId string required

    Your organization's short ID, as it appears in your issuer: https://id.trustaige.com/o/{shortId}.

Body application/json

  • type string required

    The name of the credential type to offer, as designed in the hub under Issuing.

  • claims map of string

    Values for the claims the credential type defines. Nothing about the person is required.

  • validForDays integer 1–30default 7

    How long the claim link stays open.

  • subject string · uuid

    Re-offer to a subject you already hold, when a customer lost their link. Leave it out for a new customer.

Responses

  • 201 The offer is open. Send claimUrl to the customer.
    Show response fields
    • id string required

      The offer.

    • subject string · uuid required

      The customer, as your organization's issuer knows them. Store it with your account: you need it to re-offer, read or erase.

    • state string required

      Always open for a new offer.

      One of open

    • claimUrl string · uri required

      The link that claims the credential. Send it to the customer yourself.

    • expiresAt string · date-time required

      When the link stops working.

  • 400 The request is not one the hub can act on.
  • 401 No bearer token.
  • 403 The token's app may not make this offer.
  • 404 No such organization, credential type or subject.
  • 409 The customer already holds their credential, or the admission has ended.

Errors

Errors come back as a code to branch on. What each means and what to do:

Status Code What to do
400 bad_request The body is not JSON.
400 invalid_type Name the credential type in type.
400 invalid_valid_for_days validForDays is between 1 and 30; leave it out for 7.
400 invalid_claims A claim value doesn't fit the credential type. The message says which.
403 wrong_organization The token belongs to another organization's app. Use your own organization's short ID.
403 type_not_admitted Your app is limited to other credential types. Change what it admits in the hub, or offer one of those.
403 issuer_paused Your organization isn't issuing new credentials right now. Check its plan in the hub.
404 unknown_type No live credential type has that name.
404 unknown_subject The subject you re-offered to doesn't exist in this organization.
409 already_claimed The customer already has their credential. Send them to sign in instead.
409 admission_ended This admission has ended.