Add Credentials to a Wallet

There are three ways a credential is added to an SVX Wallet:

Issuer-initiated issuance (OpenID4VCI) — the wallet acts on a credential offer, obtains an access token, and collects the issued credential.
Wallet-initiated issuance (OpenID4VCI) - the wallet initiates the issuance by selecting an issuer and credential configuration before obtaining the credential.
Direct import — an already-issued, encoded credential is stored in the wallet in a single call.

In all cases the credential is stored in the wallet, encrypted at rest, and can then be listed, viewed, presented, or deleted.

Prerequisites

An access token — all requests require a Bearer token. See Using the Wallet API.
An existing wallet. A wallet is identified by its walletId and is created with POST /wallets. See Manage Wallets.
```
POST /wallets
```
```
{ "external_reference": "wallet-240201" }
```
A key (or DID) to bind the credential to the holder. Most credentials are issued against a holder key; create one with POST /wallets/{walletId}/keys and note the returned kid. See Manage Keys.
```
POST /wallets/{walletId}/keys
```
```
{ "key": { "kty": "EC", "crv": "P-256" } }
```

Issuer-initiated issuance (OpenID4VCI)

Receiving a credential from an issuer via issuer-initiated issuance is a sequence of three calls. Each call returns a state value that links the steps of a single flow; pass it to the next call.

1. Register the credential offer

The flow begins with a credential offer from an issuer, typically delivered as an openid-credential-offer:// URI (for example, encoded in a QR code). Register the offer with the wallet to start the flow.

Endpoint

POST /wallets/{walletId}/receive

Request

{
  "credential_offer_endpoint": "openid-credential-offer://?credential_offer_uri=https://issuer.example.com/credential_offers/cfNTGRqlUMWaj9HQNpnsp4"
}

You may instead pass a credential_offer_uri directly, or an inline credential_offer object, if you already hold the offer.

Response

The response echoes the resolved offer and returns the state for the flow. The offer's grants indicate how to obtain an access token — here a pre-authorized_code grant that also requires a 4-digit transaction code (PIN).

{
  "state": "682c0278-da29-4f23-9f1c-165777bed32b",
  "credential_offer": {
    "grants": {
      "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
        "pre-authorized_code": "mSvEkWPgwQ3iOwPJRAYRgN",
        "tx_code": { "input_mode": "numeric", "length": 4 }
      }
    },
    "credential_configuration_ids": ["StudentID_sd_jwt"],
    "credential_issuer": "https://issuer.example.com"
  }
}

2. Obtain an access token

Exchange the offer for an access token from the issuer's authorization server.

Endpoint

POST /wallets/{walletId}/receive/get_access_token

Request (pre-authorized_code grant)

When the offer specifies a tx_code, supply the PIN the issuer shared with the holder.

{
  "state": "682c0278-da29-4f23-9f1c-165777bed32b",
  "tx_code": "4759"
}

Response

{
  "state": "682c0278-da29-4f23-9f1c-165777bed32b",
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dC…",
  "token_type": "bearer",
  "expires_in": 86400,
  "authorization_url": null
}

Note Authorization code grant: if the offer uses an authorization_code grant instead, this call returns an authorization_url rather than an access token. Open that URL in a browser, complete the login, and the issuer redirects back to the wallet to continue the flow. The access token is then held against the state ready for the next step.

3. Collect the credential

Request the credential, binding it to a holder key by kid (or to a did). The wallet stores the issued credential automatically and returns it.

Endpoint

POST /wallets/{walletId}/receive/get_credential

Request

{
  "state": "682c0278-da29-4f23-9f1c-165777bed32b",
  "kid": "lA5y6IC-aLCpHtf-NytvSbYGZWqAfbrgAoGn3F3l0NI"
}

Note Provide exactly one of kid or did. did is only supported for jwt_vc_json format. For the dc+sd-jwt format the holder's key is embedded as a cnf.jwk claim. For the mso_mdoc format the holder's key is embedded as DeviceKeyInfo.

Response

The credential is now stored in the wallet. id is the wallet's identifier for the stored credential, and credential is the issued credential in its encoded form.

{
  "id": "b3f1c0e2-1d4a-4b8e-9c2a-7f6d5e4c3b2a",
  "state": "682c0278-da29-4f23-9f1c-165777bed32b",
  "credential_id": "urn:uuid:58864fac-1857-40f8-9f37-8fdd4fe1cc2e",
  "credential": "eyJ0eXAiOiJkYytzZC1qd3QiLCJhbGciOiJFUzI1NiJ9…"
}

You can review in-progress and completed flows for a wallet with GET /wallets/{walletId}/receive, or a single flow with GET /wallets/{walletId}/receive/{state}.

Wallet-initiated issuance (OpenID4VCI)

Obtaining a credential from an issuer via wallet-initiated issuance is a sequence of three calls. Each call returns a state value that links the steps of a single flow; pass it to the next call.

Wallet-initiated issuance uses the OAuth 2.0 Authorization Code grant.

1. Discover the issuer's supported credentials.

Retrieve the Credential Issuer Metadata to determine the issuer identifier and the credential configuration (or scope) to request.

The following values will be required for the next step:

credential_issuer
supported_credential_configuration[].scope of the desired credential

Endpoint

GET {ISSUER}/.well-known/openid-credential-issuer

Example Response

{
  "credential_issuer": "<ISSUER URL>",
  "credential_endpoit": "<ISSUER URL>/credential",
  ...
  "credential_configurations_supported": {
    "identity_credential": {
      "scope": "identity_vc",
      "format": "dc+sd-jwt",
      ...
      "vct": "id-cred"
    }
  }
}

2. Obtain an access token

Start the authorization flow with the issuer.

Endpoint

POST /wallets/{walletId}/receive/get_access_token

Request

{
  "credential_issuer": "<ISSUER URL>",
  "scope": "identity_vc",
  "redirect_uri": "<wallet-front-end>://redirect", 
  "client_id": "<Your client ID with the issuer>" // if required
}

The response returns an authorization_url.

Open this URL in a browser and complete authentication with the issuer. Once authorization is complete, the issuer redirects back to the wallet, which then redirects to the redirect_uri supplied in the request. The wallet stores the resulting access token against the state for the next step.

Response

{
  "state": "682c0278-da29-4f23-9f1c-165777bed32b",
  "authorization_url": "<ISSUER AUTHORIZATION URL>"
}

3. Collect the credential

Request the credential, binding it to a holder key by kid (or to a did). The wallet stores the issued credential automatically and returns it.

Endpoint

POST /wallets/{walletId}/receive/get_credential

Request

{
  "state": "682c0278-da29-4f23-9f1c-165777bed32b",
  "kid": "lA5y6IC-aLCpHtf-NytvSbYGZWqAfbrgAoGn3F3l0NI"
}

Note Provide exactly one of kid or did. did is only supported for jwt_vc_json format. For the dc+sd-jwt format the holder's key is embedded as a cnf.jwk claim. For the mso_mdoc format the holder's key is embedded as DeviceKeyInfo.

Response

The credential is now stored in the wallet. id is the wallet's identifier for the stored credential, and credential is the issued credential in its encoded form.

{
  "id": "b3f1c0e2-1d4a-4b8e-9c2a-7f6d5e4c3b2a",
  "state": "682c0278-da29-4f23-9f1c-165777bed32b",
  "credential_id": "urn:uuid:58864fac-1857-40f8-9f37-8fdd4fe1cc2e",
  "credential": "eyJ0eXAiOiJkYytzZC1qd3QiLCJhbGciOiJFUzI1NiJ9…"
}

You can review in-progress and completed flows for a wallet with GET /wallets/{walletId}/receive, or a single flow with GET /wallets/{walletId}/receive/{state}.

Import a credential directly

If you already hold an issued, encoded credential, store it in the wallet in a single call — no offer or access token is involved. This is useful when a credential is obtained out of band or migrated from another store.

Endpoint

POST /wallets/{walletId}/credentials/import

Request

{
  "credential": "eyJ0eXAiOiJkYytzZC1qd3QiLCJhbGciOiJFUzI1NiJ9…",
  "format": "dc+sd-jwt"
}

credential – the encoded credential string
format – the credential format. Supported values:
Format
Description
jwt_vc_json
W3C Verifiable Credential as a JWT.
dc+sd-jwt
SD-JWT VC (selective disclosure).
mso_mdoc
ISO mdoc / mDL.

Response

The stored credential is returned, including the wallet's id for it and parsed metadata such as the issuer and credential type.

{
  "credential": {
    "id": "b3f1c0e2-1d4a-4b8e-9c2a-7f6d5e4c3b2a",
    "format": "dc+sd-jwt",
    "credential": "eyJ0eXAiOiJkYytzZC1qd3QiLCJhbGciOiJFUzI1NiJ9…",
    "created_at": "2026-06-13T09:30:00.000Z",
    "meta": {
      "vct": "StudentID",
      "issuer": "did:web:did-web.securevalue.exchange:02978ef1-8fea-46ee-82e7-6ab6e96d1633",
      "kid": "lA5y6IC-aLCpHtf-NytvSbYGZWqAfbrgAoGn3F3l0NI",
      "credential_id": "urn:uuid:58864fac-1857-40f8-9f37-8fdd4fe1cc2e"
    }
  }
}

Once stored, a credential can be listed and retrieved with GET /wallets/{walletId}/credentials, presented to a verifier, or removed. See Credentials.

Last updated 7 days ago