Skip to main content

Issue a credential

The Hovi Connect API's Credentials endpoints let you issue credentials from your own product. You send a credential offer based on one of your credential templates, and the holder accepts it in the Hovi Wallet or another supported wallet. Once a template exists, it can be reused to issue credentials to many people, and other organizations in the same ecosystem can use it too.

Before you start​

Make sure you have:

  1. An API key for your ecosystem, and the ID of the organization that issues the credential (sent in the x-organization-id header).
  2. A credential template for the credential you want to issue.
  3. For cheqd, Indicio and Polygon only: a connection with the holder. EU Digital Identity and Microsoft Entra don't use connections.

The steps below use the interactive API Reference, where you can try each request in your browser.

Steps​

Choose your ecosystem. Hovi remembers your choice on other pages.

Your ecosystem
Showing instructions forEU Digital Identity

Credential formats: JSON-LD, SD-JWT and mDoc. The example uses SD-JWT.

  1. Open the API Reference and select the EU Digital Identity Ecosystem API under Hovi Connect API. Selecting the EU Digital Identity Ecosystem API
  2. Go to the Credentials section. The Credentials section
  3. Open POST - Offer Credential (SD-JWT) and click Test Request. The Offer Credential (SD-JWT) endpoint
  4. Enter your API key as a Bearer Token, fill in the body parameters and click Send. Sending the request
  5. The response includes credentialOfferUrl, a link to a QR code that the holder scans with their wallet, and credentialOfferUri, the same offer for a wallet to open directly. If you asked for a transaction code, the response also includes transactionCode. The credential offer QR code

Choose how the holder gets the credential

EU Digital Identity supports two issuing flows. Set the flow with codeflow.

  • Pre-authorized code flow ("pre-authorized", the default): the holder scans the offer and receives the credential. You can also ask for a transaction code (a one-time PIN) that the holder enters in their wallet before they receive the credential. Turn it on with preAuthorizedCodeflowConfig. The code has 6 to 10 digits (6 by default):

    {
    "credentialTemplateId": "<CREDENTIAL_TEMPLATE_ID>",
    "credentialValues": { "name": "Alex Smith" },
    "codeflow": "pre-authorized",
    "preAuthorizedCodeflowConfig": {
    "useTransactionCode": true,
    "transactionCode": {
    "length": 6,
    "description": "Enter the code we sent you"
    }
    }
    }

    The response's transactionCode is the code to give to the holder.

  • Authorization code flow ("authorization"): the holder's wallet sends them to your own sign-in system, for example your company or university login, and they receive the credential after they sign in. Details such as their name and email can be filled in from the sign-in. First add an authorization server to your organization.

    Then pass authorizationCodeflowConfig:

    • authorizationServerId (required): which of your organization's servers the holder signs in with.
    • signInScopes (optional): the scopes asked for at sign-in for this offer only, instead of the server's defaults. openid is always added.
    • walletRedirectUris (optional): the wallet redirect URIs allowed for this offer only, instead of the server's defaults.
    • issuerState (optional): your own value linking the sign-in to this offer, unique for each offer. If you leave it out, Hovi generates one.
    • offerScope (optional): the scope in the offer's authorization_code grant. If you leave it out, the credential's scope is used (see credential templates).
    {
    "credentialTemplateId": "<CREDENTIAL_TEMPLATE_ID>",
    "credentialValues": { "memberId": "M-0001" },
    "codeflow": "authorization",
    "authorizationCodeflowConfig": {
    "authorizationServerId": "<AUTHORIZATION_SERVER_ID>",
    "signInScopes": ["profile", "email"]
    }
    }

    Details from the sign-in: template attributes marked authorization: true are filled from the holder's sign-in, so leave them out of credentialValues. Their names must match what the sign-in system returns exactly, for example given_name, family_name or email, and you must ask for the matching scopes (profile for names, email for email). If a required attribute isn't returned, the credential isn't issued.

Changed in v0.8.9

authorizationServerId is now required: Hovi no longer uses your organization's first server by default. authorizationServerUrl is removed; use authorizationServerId instead.

Revoke a credential​

EU Digital Identity only. You can revoke an SD-JWT credential so it can no longer be used. Revocation works only for credentials issued from an SD-JWT template created with supportRevocation set to true, and only through the API.

info

Available on every paid plan, but not during the free trial. During the trial, the request returns 403 Forbidden.

Send POST - Revoke Credential with your API key and x-organization-id, and the credentialExchangeId from the offer response:

{
"credentialExchangeId": "<CREDENTIAL_EXCHANGE_ID>"
}

What happens next​

Once the holder accepts the offer, the credential is stored in their wallet and they can share it whenever someone needs to check it. To get notified when that happens, set up webhooks. To check credentials from your product, see Verify a credential. For which formats each ecosystem supports, see Compatibility.