Skip to main content
Version: 1.0 OpenAPI spec

Business Wallet API

API to create and verify verifiable credentials.

The Business Wallet API is the programmatic half of the Credenco Business Wallet. The most common tasks (issue a credential, ask another party for one, manage wallets, keys and users) are also available as REST calls, so you can drive the wallet from your own backend. Credential exchange follows the OpenID4VC protocols and the W3C Verifiable Credentials data model, so the other side does not have to be a Credenco wallet.

This page gets you from nothing to your first call. Every endpoint is documented in the menu on the left.

What you can do with the API​

GroupWhat it covers
CredentialsIssue credentials to a Business Wallet or a phone, follow issuance status, revoke; request and verify credentials from another party over OpenID4VP.
Wallet administrationWallets, identifiers and keys, the credentials your wallet holds, users (including email verification) and roles.
Profile & contactsYour public profile and your trusted contacts.
ApplicationsSend an invoice, or deliver a credential straight to a recipient's DID inbox.
IntegrationOutbound integration channels and the event deliveries they produced.
DeprecatedEndpoints that still work but have a supported replacement. Don't build anything new on these.

Before you start​

You need three things.

  1. A Business Wallet. Credenco hosts it for you, or you run it on-premise; the API is the same either way.
  2. API credentials. An OAuth client or an API key, created in the wallet under Settings → API access.
  3. The right roles. Most endpoint pages name the role they need under Required Role: WALLET_READ for reading wallet details, for example. Grant those roles to the client or key you just created, and nothing more.

Base URL​

Every endpoint lives on your own wallet's host, the same host you use for the web UI:

https://your-wallet.credenco.com

Paths are absolute and most carry a version segment, so a full request URL looks like https://your-wallet.credenco.com/api/v2/credential/issue.

Prefer to work from the specification itself? The OpenAPI spec link at the top of this page downloads it, ready for a code generator or an HTTP client, and the Swagger entry at the bottom of the API menu opens the same reference in Swagger UI.

Authenticate your requests​

Both methods are managed under Settings → API access; see Authentication for the full story.

An API key goes in the x-api-key header:

curl https://your-wallet.credenco.com/api/wallets \
  -H "x-api-key: YOUR_API_KEY"

An OAuth client exchanges its client ID and secret for an access token first:

curl -X POST https://iam.credenco.com/realms/organization-wallet/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=wallet-YOUR_WALLET_EXTERNAL_KEY-YOUR_CLIENT_NAME \
  -d client_secret=YOUR_CLIENT_SECRET

Swap iam.credenco.com for the identity provider that serves your environment. The client ID is the full value shown on the API access screen; it starts with wallet- and your wallet's external key, which is what scopes the token to your wallet. Send the token you get back as a bearer token:

curl https://your-wallet.credenco.com/api/wallets \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Keys and client secrets carry every role you granted them, so keep them on your server. Never ship one in a browser or mobile app.

Make your first call​

Listing your wallets is the shortest request that proves your credentials work:

curl https://your-wallet.credenco.com/api/wallets \
  -H "x-api-key: YOUR_API_KEY"
{
  "content": [
    {
      "externalKey": "2a0ae7d8-2b17-4d05-94ab-02a1cc74606f",
      "displayName": "My Business Wallet",
      "walletState": "OPERATIONAL"
    }
  ],
  "page": { "size": 10, "number": 0, "totalElements": 1, "totalPages": 1 }
}

Keep that externalKey. Most endpoints are scoped to one wallet and take it as the walletExternalKey path parameter, as in GET /api/v1/wallets/{walletExternalKey}/credentials.

If you get a 401, the key or token was not accepted. A 403 means it was accepted, but the client is missing the role the endpoint requires.

Issue your first credential​

  1. In the web UI, create a credential template for what you want to issue. Its key is the template_id you pass to the API.
  2. Call Start issue Credential with that template_id, the attribute values and a correlation id of your own (optional; one is generated and returned if you leave it out). The response holds a request_uri to redirect the holder's browser to, or a QR code as a data URI, if you ask for one.
  3. Poll Get issue status with the same correlation id to see whether the holder accepted, and to get the revocation_uuid you need later to revoke the credential.

Issue a credential from your backend walks through issuing to a Business Wallet and to a personal wallet app, with full request and response bodies. To ask another party for a credential instead, start at Create authorization request and session and the Receive Credentials guide.

How this reference is organised​

  • Each endpoint page shows the method and path, the parameters, the request and response schemas and every status code, plus a Send API Request panel that fires a real request with your own credentials.
  • Where an endpoint needs a specific role, its description carries a Required Role table.
  • Most list endpoints are paged. Pass page (zero-based), size (10 by default) and sort as property,asc or property,desc; the response wraps the rows in content and adds a page object with size, number, totalElements and totalPages. The few that are not paged return a plain JSON array; the parameter list on the endpoint page tells you which is which.
  • Endpoints under Deprecated still work and still get fixes, but each has a replacement elsewhere in this reference. Use the replacement for anything new.

Next steps​

Authentication​

Security Scheme Type:

oauth2

OAuth Flow (clientCredentials):

Scopes:

    Contact

    Business Wallet: info@credenco.com

    Last updated on