verifiableCredentials

Every organization can issue verifiable credentials: SD-JWT VCs (IETF SD-JWT-based Verifiable Credentials) that people keep in digital wallets and present with only the claims a verifier needs. Credentials are bound to a key the holder proved they own, and they are revoked or suspended through an IETF Token Status List that verifiers read. Wallets get credentials over OpenID4VCI from endpoints mounted at {basePath}/vc/{tenantId}. Apps can call request directly. The group exists when the deployment sets the verifiableCredentials option; otherwise every method fails with FEATURE_DISABLED. The guide is Verifiable credentials.

available

The enabled types the caller may request for themselves right now: vc:request allowed on credential-type/{name}, MFA when the type asks, and not in a "view as" session or a delegated agent session. No permission needed.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/available" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.verifiableCredentials.available(
  credential: CredentialInput,
  input: { tenantId: string },
): Promise<VcCredentialTypeView[]>

createOffer

An OpenID4VCI credential offer with a pre-authorized code, and its openid-credential-offer:// link for a wallet to scan. It is for the caller (vc:request, like request) or, with identityId, for someone else (iam:vc:issue). txCode: true adds a 6-digit PIN the wallet asks for; give it to the person separately. The code works once and expires after the deployment's offerLifetimeMs. A token request without the PIN does not count as a guess; five wrong PINs end the offer. For self-service offers, policy and MFA are decided again when the wallet redeems the offer, and the credential ends with the grants that allow it. An administrator's offer records them as the credential's issuedBy.

Used inVerifiable credentials

• Audited as: vc:offer:create; refused redemptions (wrong PIN, lockout, access changed) as a denied vc:offer:redeem.
• Errors: as request; IDENTITY_INACTIVE for someone who is not an active member.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/createOffer" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "type": "<type>"
}'

iam.api.verifiableCredentials.createOffer(
  credential: CredentialInput,
  input: { tenantId: string; type: string; identityId?: string; txCode?: boolean },
): Promise<VcOfferResult>

createType

Defines a credential type: a name, a displayName and description for wallets, card colors, a lifetime (default 30 days, at most the deployment's maxLifetimeMs), requireMfa, and 1 to 32 claims. Each claim takes its value from a source: email, emailVerified, name, identityId, kind, tenantId, tenantName, teams, department, a declared identity attribute (attribute:{name}) or a static value. It is selectively disclosable unless selective: false, and left out when missing unless required. The vct defaults to {issuer}/types/{name}; a custom one may not sit under another organization's issuer on this deployment. The first type also creates the tenant's issuer key.

Used inVerifiable credentials

• Permission: iam:vc:manage on iam/vc/types/{name}.
• Errors: CONFLICT for a name in use; INVALID_INPUT for reserved or repeated claim names, unknown sources, invalid colors, or a vct under another organization's issuer.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/createType" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "name": "<name>",
  "displayName": "<displayName>",
  "claims": [
    {}
  ]
}'

iam.api.verifiableCredentials.createType(
  credential: CredentialInput,
  input: VcCredentialTypeInput,
): Promise<VcCredentialTypeView>

deleteType

Deletes a type and its pending offers.

• Permission: iam:vc:manage on iam/vc/types/{name}.
• Errors: RESOURCE_IN_USE while valid credentials of the type exist.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/deleteType" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "name": "<name>"
}'

iam.api.verifiableCredentials.deleteType(
  credential: CredentialInput,
  input: { tenantId: string; name: string },
): Promise<{ deleted: boolean }>

getType

One credential type.

• Permission: iam:vc:read on iam/vc/types/{name}.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/getType" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "name": "<name>"
}'

iam.api.verifiableCredentials.getType(
  credential: CredentialInput,
  input: { tenantId: string; name: string },
): Promise<VcCredentialTypeView>

issuerMetadata

The tenant's OpenID4VCI credential issuer metadata: endpoints, and every enabled type with its format (dc+sd-jwt), vct, binding methods, proof algorithms and wallet display. The same document is served at /.well-known/openid-credential-issuer{basePath}/vc/{tenantId}. Public.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/issuerMetadata" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.verifiableCredentials.issuerMetadata(
  input: { tenantId: string },
): Promise<{
  credential_issuer: string;
  credential_endpoint: string;
  nonce_endpoint: string;
  display: { name: string; locale: string }[];
  credential_configurations_supported: {
    [k: string]: {
      format: string;
      vct: string;
      scope: string;
      cryptographic_binding_methods_supported: string[];
      credential_signing_alg_values_supported: string[];
      proof_types_supported: { jwt: { proof_signing_alg_values_supported: string[] } };
      credential_metadata: {
        display: {
          text_color?: string | undefined;
          background_color?: string | undefined;
          description?: string | undefined;
          name: string;
          locale: string;
        }[];
        claims: {
          display?: { name: string; locale: string }[] | undefined;
          path: string[];
        }[];
      };
    };
  };
}>

listIssued

Issued credentials, newest first, by type, identityId or state (valid, suspended, revoked, expired), with limit (at most 500) and offset. Records hold claim names, never values.

• Permission: iam:vc:read on iam/vc/credentials.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/listIssued" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.verifiableCredentials.listIssued(
  credential: CredentialInput,
  input: {
    tenantId: string;
    type?: string;
    identityId?: string;
    state?: VcIssuedView['state'];
    limit?: number;
    offset?: number;
  },
): Promise<{ credentials: VcIssuedView[]; total: number }>

listKeys

The issuer's signing keys, oldest first: active, previous (still published, so its credentials verify) and retired.

• Permission: iam:vc:read on iam/vc/keys.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/listKeys" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.verifiableCredentials.listKeys(
  credential: CredentialInput,
  input: { tenantId: string },
): Promise<VcIssuerKeyView[]>

listTypes

Every credential type of the tenant, by name.

• Permission: iam:vc:read on iam/vc/types.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/listTypes" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.verifiableCredentials.listTypes(
  credential: CredentialInput,
  input: { tenantId: string },
): Promise<VcCredentialTypeView[]>

mine

The caller's own credentials in the tenant, newest first (the last 100), with their state. Refused for delegated agent sessions (ACCESS_DENIED).

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/mine" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.verifiableCredentials.mine(
  credential: CredentialInput,
  input: { tenantId: string },
): Promise<VcIssuedView[]>

nonce

A single-use proof nonce (c_nonce) for the tenant's issuer, valid five minutes. Nonces are signed rather than stored, so handing one out writes nothing; a proof spends its nonce. Public.

Used inVerifiable credentials

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/nonce" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.verifiableCredentials.nonce(
  input: { tenantId: string },
): Promise<{ nonce: string; expiresIn: number }>

reinstate

Lifts a suspension.

• Permission: iam:vc:revoke on iam/vc/credentials/{id}.
• Errors: INVALID_TRANSITION unless the credential is suspended.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/reinstate" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "credentialId": "<credentialId>"
}'

iam.api.verifiableCredentials.reinstate(
  credential: CredentialInput,
  input: { tenantId: string; credentialId: string },
): Promise<VcIssuedView>

request

Issues a credential of type to the caller, bound to the key in proof. The proof is an openid4vci-proof+jwt with the holder's public key in its jwk header, the issuer URL as aud, and a nonce from nonce. Holder keys may be ES256, ES384 or EdDSA. Returns the SD-JWT VC and its record. The credential ends at the type's lifetime, the person's scheduled account expiry, or the end of the time-limited grant that allows vc:request (an expiring binding or membership, a just-in-time activation, an access window), whichever comes first. From an assumed role or temporary credentials it ends with that session.

Used inVerifiable credentials

• Permission: a session, not a delegated agent session; vc:request on credential-type/{type}, and MFA when the type requires it.
• Audited as: vc:credential:issue (type, holder key thumbprint, claim names); a refusal as a denied vc:request.
• Errors: ACCESS_DENIED; MFA_REQUIRED; TYPE_DISABLED; IMPERSONATION_RESTRICTED; INVALID_PROOF; INVALID_NONCE; CLAIM_UNAVAILABLE when a required claim has no value; ACCESS_EXPIRING when the grant that allows it ends within a minute.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/request" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "type": "<type>",
  "proof": "<proof>"
}'

iam.api.verifiableCredentials.request(
  credential: CredentialInput,
  input: { tenantId: string; type: string; proof: string },
): Promise<{ credential: string; record: VcIssuedView }>

retireKey

Stops publishing a previous key, after which credentials it signed no longer verify.

• Permission: iam:vc:manage on iam/vc/keys.
• Errors: RESOURCE_IN_USE while valid credentials it signed exist, unless force: true, which revokes them; INVALID_TRANSITION for the active key.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/retireKey" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "kid": "<kid>"
}'

iam.api.verifiableCredentials.retireKey(
  credential: CredentialInput,
  input: { tenantId: string; kid: string; force?: boolean },
): Promise<VcIssuerKeyView>

revoke

Revokes a credential for good: its status list entry becomes invalid. Holders may revoke their own credentials from their own session; delegated agent sessions and credentials narrowed by a session policy, and anyone revoking someone else's, need the permission.

• Permission: none for your own from your own session; otherwise iam:vc:revoke on iam/vc/credentials/{id}.
• Audited as: vc:credential:revoke (own) or iam:vc:revoke.
• Errors: INVALID_TRANSITION for a credential already revoked.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/revoke" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "credentialId": "<credentialId>"
}'

iam.api.verifiableCredentials.revoke(
  credential: CredentialInput,
  input: { tenantId: string; credentialId: string; reason?: string },
): Promise<VcIssuedView>

rotateKey

Starts signing with a new ES256 key. The current one stays published as previous.

• Permission: iam:vc:manage on iam/vc/keys.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/rotateKey" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.verifiableCredentials.rotateKey(
  credential: CredentialInput,
  input: { tenantId: string },
): Promise<VcIssuerKeyView>

status

The issuer at a glance: its identifier and metadata URL, the published keys, the number of credential types, issued credentials by state (valid, suspended, revoked, expired), and status lists.

• Permission: iam:vc:read on iam/vc/issuer.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/status" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>"
}'

iam.api.verifiableCredentials.status(
  credential: CredentialInput,
  input: { tenantId: string },
): Promise<{
  issuer: string;
  metadataUrl: string;
  keys: VcIssuerKeyView[];
  types: number;
  credentials: { valid: number; suspended: number; revoked: number; expired: number };
  statusLists: number;
}>

suspend

Suspends a valid credential (a lost phone). Verifiers see it as suspended until reinstate.

• Permission: iam:vc:revoke on iam/vc/credentials/{id}.
• Errors: INVALID_TRANSITION unless the credential is valid.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/suspend" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "credentialId": "<credentialId>"
}'

iam.api.verifiableCredentials.suspend(
  credential: CredentialInput,
  input: { tenantId: string; credentialId: string; reason?: string },
): Promise<VcIssuedView>

updateType

Changes a type's display, claims, lifetime, requireMfa or enabled. The name and vct never change.

• Permission: iam:vc:manage on iam/vc/types/{name}.

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/updateType" \
  -H "Authorization: Bearer $BETTER_IAM_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "tenantId": "<tenantId>",
  "name": "<name>"
}'

iam.api.verifiableCredentials.updateType(
  credential: CredentialInput,
  input: VcCredentialTypeUpdate,
): Promise<VcCredentialTypeView>

verify

Verifies a presentation of a credential this deployment issued. It checks the issuer's signature (the tenant's current or previous keys), validity times, every disclosure against the signed digests, the key-binding JWT (audience, nonce, freshness, sd_hash) and the credential's status. Returns { valid: true, claims, disclosed, type, ... }, or { valid: false, reason } with reasons such as revoked, suspended, wrong-audience, wrong-nonce, bad-disclosure or unknown-issuer. audience and nonce are required (INVALID_INPUT without them), since a presentation captured by one verifier would otherwise verify for any other; the result's keyBinding (audience, nonce, issuedAt) is there for your own record of accepted nonces. Public.

Used inVerifiable credentials

curl -X POST "$IAM_URL/api/iam/verifiableCredentials/verify" \
  -H "Content-Type: application/json" \
  -H "X-Better-IAM: 1" \
  -d '{
  "presentation": "<presentation>"
}'

iam.api.verifiableCredentials.verify(
  input: { presentation: string; audience?: string; nonce?: string; tenantId?: string },
): Promise<VcVerification>