Skip to main content

Creating a Credential

Creating a credential assembles the data structure in the system, including schema, claims, issuer identity, and protocol, ready to be issued to a wallet holder.

Required parameters​

Credential schema​

A credential schema defines the type of credential you are issuing. It specifies the credential format, suspension and revocation method, expected claims (keys and datatypes), visual rendering properties, and wallet key requirements.

When creating a credential, choose a schema that has already been created. See Credential Schemas.

Claims​

Use the claimValues[] object to assert claims during credential creation.

For each claim, three fields are required:

{
  "claimValues": [
    {
      "claimId": "31e4e82e-1663-4775-ad6a-bf828037eace",
      "path": "Family plan members/0/Full name",
      "value": "Jim Smith"
    }
  ]
}

path points to the claim key within the credential schema structure, using a JSON Pointer format (root/nested_array/0):

  • Single attribute — the path is just the attribute key:
  { "claimId": "...", "path": "First name", "value": "Alice" }
  • Array — root followed by index (same claimId for each entry):
  { "claimId": "...", "path": "Attribute key/0", "value": "First value" },
  { "claimId": "...", "path": "Attribute key/1", "value": "Second value" }
  • Object — root followed by the nested attribute key:
  { "claimId": "...", "path": "Object/Attribute key 1", "value": "Value 1" },
  { "claimId": "...", "path": "Object/Attribute key 2", "value": "Value 2" }
  • Array within an object — append the index:
  { "claimId": "...", "path": "Object/Attribute key 2/0", "value": "Value 2" }

If a required claim is missing, a value is the wrong datatype, or the data structure doesn't match the schema, the request returns an error and the credential is not created.

See Datatypes.

Issuer identifier​

Specify the issuer — the identifier used to sign the credential and used by the holder's wallet to authenticate you as a trusted issuer.

tip

If you have issues with your chosen identifier, check the following capabilities in your credential format configuration:

  • issuanceIdentifierTypes
  • issuanceDidMethods (if using DIDs)
  • signingKeyAlgorithms

Issuance protocol​

Specify the protocol used to transmit the credential to the holder's wallet.

Reference the instance name, not the type, since multiple instances of a single protocol type can be configured:

"issuanceProtocol": {
  "OPENID4VCI_FINAL1_MOD_1": {         # Reference this
    "type": "OPENID4VCI_FINAL1",       # Not this
    ...
  }
}
tip

If you have issues with your chosen protocol, check the following capabilities in your credential format and issuance protocol configuration, respectively:

  • issuanceExchangeProtocols
  • didMethods (if using DIDs)

Optional parameters​

  • issuerKey and issuerCertificate: if your identifier contains multiple keys in its assertion method or certificates in a chain, use these to specify which to use for signing. Omitting uses the first listed.
  • redirectUri: a URL or deep link the holder is taken to after accepting the credential.
  • webhookDestinationUrl: a URL to receive issuance event notifications. See Webhooks.
  • profile: Choose a country profile to associate this credential with.

Example request​

-d '{
  "claimValues": [
    {
      "claimId": "38569fa1-10ba-4ad6-abb5-0c7dfa09b6a3",
      "path": "Name",
      "value": "Jane A. Smith"
    },
    {
      "claimId": "c62e6f62-e4f5-4416-a0be-f371aa1e7e86",
      "path": "Address/Street",
      "value": "123 Maple St."
    },
    {
      "claimId": "058597d2-5048-4b51-b434-ae2b72086f4b",
      "path": "Address/City",
      "value": "Springfield"
    },
    {
      "claimId": "3899e362-b897-4d4a-8d11-70b1875fa532",
      "path": "Address/Postal code",
      "value": "62701"
    },
    {
      "claimId": "18f1bd79-d7f3-4414-bc29-95f399cbb1cc",
      "path": "Date of birth",
      "value": "1985-01-14T23:00:00.000Z"
    },
    {
      "claimId": "abd3cb68-3dca-43ce-a94c-dd69853cd45d",
      "path": "Email",
      "value": "jsmith85@example.com"
    }
  ],
  "credentialSchemaId": "ad0e33be-09ca-4b84-8bb6-be761cbf2a7d",
  "issuanceProtocol": "OPENID4VCI_FINAL1",
  "issuer": "a635a9e2-e6f0-4ef3-9800-6e9c38e5a258",
  "redirectUri": "https://www.example.com/accepted"
}'

Response​

A successful request returns the id of the created credential. Use this ID to share the credential.

Next step​

Once a credential has been created, share it with the holder. See Share a Credential.