Igrantio API Issuer

iGrant.io OpenID4VC API - Issuer

When to use

Use this skill when you issue credentials from an iGrant.io organisation. It covers the 26 operations of the Issuer group: the issuer global configuration, credential definitions, credential issuance, issuance history, revocation status, scopes, and transaction data validation.

Use it when you must:

• create or change a credential definition, or read the ready-made templates;
• issue a credential and get the credential offer URI and the correlation id;
• complete a deferred issuance;
• revoke or suspend a credential that you issued;
• read or delete the issuance history of your organisation.

For the holder side, read igrantio-api-holder. For the verifier side, read igrantio-api-verifier.

Protocol scope

• The issuer implements OpenID4VCI 1.0. Set version to version_01 on the credential definition. Always send version, because the issuer falls back to an earlier version of the specification when you leave the field out. You cannot change the value after you create the credential definition.
• Claims use claim path pointers (claims.claims[].path), not the older flat claim maps.
• Draft protocol versions are not a supported surface of this group.
• Presentation Exchange is not supported. When an issuance also asks the holder for a credential (presentationDefinitionId), the request uses a stored presentation definition that holds a DCQL query.

Authentication

Send the API key in the Authorization header with the ApiKey prefix and a space:

Authorization: ApiKey <your-api-key>

Demo base URL: https://demo-api.igrant.io. The bundle also lists https://api.igrant.io (production) and https://staging-api.igrant.io. The API key stays on your server. The browser never holds it.

Endpoint reference

Issuer global configuration

Defaults for every credential definition of the organisation: branding, validity, and Credential Issuer Metadata settings. An organisation holds one issuer global configuration; a second create request fails with HTTP 400.

The update operation replaces the full record. Read the configuration first and send back every field that you want to keep, because a field that you leave out goes back to its default value.

Credential definitions

Issuance and history

Scopes and transaction data

Key fields

Create credential definition

POST /v2/config/digital-wallet/openid/sdjwt/credential-definition

Mandatory: label (minimum 3 characters) and credentialDefinitions (minimum one entry). The labels Payment User Credential, Payment Card Credential, Payment Account Credential, PID Issuance and Photo ID Issuance are reserved for the platform.

Record-level fields, valid only at the top level:

Each entry of credentialDefinitions[] is one credential configuration that the issuer publishes in the Credential Issuer Metadata. Only credentialFormat is mandatory in an entry.

Do not repeat version, trustAnchor, kid or enforceWUA inside an entry, and do not put a configuration field such as credentialFormat or claims at the top level. The issuer refuses both requests.

Claim path pointers. claims and credentialDefinition both hold a mandatory claims array. Each item holds:

• path (mandatory, minimum one element) - the pointer that selects the claim. Each element is a string for an object key, an integer for an array index, or null for every element of an array.
• mandatory (boolean) - the issuer reads a missing field as true.
• limitDisclosure (boolean) - the holder can disclose the claim selectively. This field belongs to the claims object only.

For mso_mdoc, the first element of path is the mDoc namespace, the path holds at least two elements, and every path of the configuration uses the same first element. For jwt_vc_json, the first element is credentialSubject.

{
  "label": "Issue Portable Document A1",
  "version": "version_01",
  "trustAnchor": "did:key",
  "credentialDefinitions": [
    {
      "credentialFormat": "dc+sd-jwt",
      "vct": "urn:eu.europa.ec.eudi:pid:1",
      "validationPath": "$",
      "supportRevocation": true,
      "revocationMethod": "status_list",
      "claims": {
        "claims": [
          { "path": ["given_name"], "mandatory": true, "limitDisclosure": true },
          { "path": ["address", "country"], "mandatory": false }
        ]
      }
    }
  ]
}

The create response returns an id for each entry of credentialDefinitions. Keep those values: the issue operation uses them to match claims to a configuration.

Issue credential

POST /v2/config/digital-wallet/openid/sdjwt/credential/issue

Only issuanceMode is mandatory.

Inside credential (and each entry of credentials), the claim carrier follows the format: type plus credentialSubject for jwt_vc_json, vct plus claims for dc+sd-jwt, doctype plus claims for mso_mdoc. id names the credential definition entry. credentialMetadata is free-form: the issuer stores it and returns it unchanged. Any other member passes through as well.

The response is HTTP 200, not 201. It holds credentialHistory, which is one object when the issuance makes one exchange record, and an array when the credential definition makes more than one.

Fields to read from credentialHistory:

• credentialExchangeId - the correlation id. Use this camel-case field in new integrations. CredentialExchangeId and id hold the same value.
• credentialOffer - the openid-credential-offer:// URI. Render it as a QR code or open it as a deep link.
• status - offer_sent, offer_received, token_issued, credential_issued, credential_acked, credential_accepted, credential_deleted, issuance_denied.
• credentialStatus - pending or ready.
• issuanceMode, isPreAuthorised, isAccessed, isTokenAccessed.

A field with no value comes back with its empty value: "", 0, false, or null.

Issue a deferred credential

PUT /v2/config/digital-wallet/openid/sdjwt/credential/history/{credentialExchangeId}

The body holds a mandatory credential object. Use credentialSubject for jwt_vc_json, and claims for dc+sd-jwt and mso_mdoc. Add id to name the entry of credentialDefinitions that the claims fill. For mso_mdoc, the top key of claims is the doctype namespace.

Update the revocation status

PUT /v2/config/digital-wallet/openid/sdjwt/credential/history/{credentialExchangeId}/revocation-status

The body holds the mandatory revocationStatus: Operational reactivates a suspended credential, Revoked invalidates it permanently, and Suspended invalidates it for the moment. The credential definition must set supportRevocation to true.

Preview a credential definition URI

POST /v2/config/digital-wallet/openid/sdjwt/credential-definition/preview takes the mandatory credentialDefinitionUri (an HTTP or HTTPS URI). Use it to check a claims schema before you put the URI in a credential definition.

Validate transaction data

POST /v2/config/digital-wallet/openid/sdjwt/transaction-data takes the mandatory paymentWalletAttestation and transactionDataHashesAlg. The algorithm array holds exactly one value, and that value must be sha-256. Send the payload in transactionData (plain JSON) or in transactionDataBase64 (base64url), but not in both. Read transactionDataVerified in the response for the result.

Sandbox call style

Every Issuer operation except the three read-only asset operations carries the optional X-SandboxOrgId header. Those three exceptions are the list credential definition templates operation, the read logo image operation, and the read cover image operation.

• With a bearer access token, send X-SandboxOrgId: <sandboxOrgId>. The service then runs the call against the wallet of that sandbox organisation and not against the main wallet. Leave the header out to use the main wallet.
• With an API key, the header does nothing. The service takes the sandbox organisation from the key. Bind the key first with PUT /v2/config/admin/apikey/{apiKeyId}/sandbox-org.
• X-SubwalletId is the deprecated name of the header. The service still accepts it, and X-SandboxOrgId wins when you send both.
• The sandbox organisation must exist, must belong to your organisation, and must be deployed. Any other identifier fails with HTTP 400.

Read igrantio-api-sandboxes for the sandbox organisation lifecycle.

Cross-references

• igrantio-ows-overview - architecture, glossary, and the shared contracts.
• igrantio-api-holder - the wallet that takes the credential offer.
• igrantio-api-verifier - the DCQL query that a dynamic credential request uses.
• igrantio-api-key-management - the signing key that kid names.
• igrantio-api-webhooks - the issuance events that tell you when the holder answered.
• igrantio-api-sandboxes - the sandbox organisation lifecycle.

Documentation is the source of truth

This skill mirrors the iGrant.io OpenID4VC API documentation. If this skill and the linked documentation disagree, the documentation wins. Before you rely on a payload shape, fetch the linked page, or the raw specification at https://docs.igrant.io/openapispecifications/oid4vc.yaml, and check for updates. Follow the documentation and report the drift so this skill can be corrected.

• Issuer API index: https://docs.igrant.io/docs/developer-apis/
• Workflow, issue a credential (OID4VCI): https://docs.igrant.io/docs/openID4vci-issue-credential-intime/