Cloud Wallet API

Holder-side credential management: create wallets, receive invitations, accept credentials, and respond to proof requests.

Overview

The Cloud Wallet API provides a holder-side interface for managing decentralized identity wallets. Using this API, a user can:

• Create a personal cloud wallet tied to their account.
• Configure the underlying agent’s base wallet.
• Establish DIDComm connections with issuers and verifiers.
• Receive and accept verifiable credential offers.
• Respond to proof presentation requests.
• Create and manage DIDs within the wallet.
• Send and receive basic messages over established connections.

All endpoints require a JWT bearer token. The userId and email are resolved from the authenticated token — they do not need to be included in the request body.

---

Holder Journey

1. Configure base wallet (first-time setup)

   Call POST /configure/base-wallet with the agent endpoint and credentials to bind the underlying agent wallet to the user’s account.

2. Create a cloud wallet

   Call POST /create-wallet with a wallet label to provision a new tenant wallet for the user.

3. Receive a connection invitation

   When an issuer or verifier shares an invitation URL, call POST /receive-invitation-url with the invitationUrl to establish a DIDComm connection.

4. Accept a credential offer

   Once a connection exists, an issuer can offer a credential. Call POST /accept-offer with the credentialRecordId and desired autoAcceptCredential behavior to accept it.

5. Respond to a proof request

   When a verifier requests a proof, call POST /proofs/accept-request with the proofRecordId to present the matching credential.

---

Endpoints

Configure Base Wallet

Configures the base agent wallet for the authenticated user. This is a one-time setup step required before creating a cloud wallet.

walletKey · string · required

The wallet encryption key used by the agent.

apiKey · string · required

API key for authenticating with the agent endpoint.

agentEndpoint · string · required

The agent’s base URL. Must be a valid protocol://host:port or domain (e.g., http://0.0.0.0:4001).

curl -X POST https://localhost:5000/v1/configure/base-wallet \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "walletKey": "xxx-xxxx-xxxx",
    "apiKey": "xxx-xxxx-xxxx",
    "agentEndpoint": "http://0.0.0.0:4001"
  }'

statusCode · number

201 on success.

message · string

Human-readable result message.

data · object

Configuration result from the agent.

---

Create Cloud Wallet

Provisions a new cloud wallet for the authenticated user.

label · string · required

Display label for the wallet (e.g., "Credential Wallet"). Must not be empty.

connectionImageUrl · string

Optional URL for the wallet’s profile image (e.g., "https://picsum.photos/200").

curl -X POST https://localhost:5000/v1/create-wallet \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My Credential Wallet",
    "connectionImageUrl": "https://picsum.photos/200"
  }'

statusCode · number

201 on success.

message · string

Human-readable result message.

data · object

The created wallet object, including the tenant ID.

---

Create Connection Invitation

Creates a DIDComm out-of-band connection invitation that can be shared with another party.

label · string

Optional human-readable label for the connection.

alias · string

Optional alias for identifying this connection locally.

imageUrl · string

Optional image URL associated with this connection.

multiUseInvitation · boolean

When true, the invitation URL can be used by multiple parties.

autoAcceptConnection · boolean

When true, the connection is accepted automatically without manual approval.

goalCode · string

Optional goal code describing the intent of the connection.

goal · string

Optional free-text goal description.

handshake · boolean

Whether to include a handshake in the invitation.

handshakeProtocols · string[]

Array of handshake protocol URLs (e.g., ["https://didcomm.org/didexchange/1.x"]).

invitationDid · string

Optional DID to use in the invitation.

recipientKey · string

Optional recipient verification key.

curl -X POST https://localhost:5000/v1/connections/invitation \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "CREDEBL Issuer",
    "multiUseInvitation": false,
    "autoAcceptConnection": true
  }'

---

Get All Connections

Returns all DIDComm connections for the authenticated user’s wallet, with optional filters.

outOfBandId · string

Filter by the out-of-band invitation ID (e.g., e315f30d-9beb-4068-aea4-abb5fe5eecb1).

alias · string

Filter connections by alias (e.g., Test).

myDid · string

Filter by the local DID used in the connection.

theirDid · string

Filter by the remote party’s DID.

theirLabel · string

Filter by the remote party’s label (e.g., Bob).

curl -X GET "https://localhost:5000/v1/connections?theirLabel=Acme+Corp" \
  -H "Authorization: Bearer <token>"

---

Get Connection by ID

Retrieves details for a specific connection.

connectionId · string · required

The connection record ID.

curl -X GET https://localhost:5000/v1/connection/e315f30d-9beb-4068-aea4-abb5fe5eecb1 \
  -H "Authorization: Bearer <token>"

---

Receive Invitation by URL

Accepts an out-of-band invitation URL to establish a new DIDComm connection.

invitationUrl · string · required

The full invitation URL received from the inviting party.

alias · string

Optional alias to assign to this connection.

label · string

Optional label to assign to this connection.

imageUrl · string

Optional image URL to associate with this connection.

autoAcceptConnection · boolean

When true, automatically accepts the connection without a separate confirmation step.

autoAcceptInvitation · boolean

When true, automatically accepts the invitation.

reuseConnection · boolean

When true, reuses an existing connection if one already exists with the inviting party.

acceptInvitationTimeoutMs · integer

Timeout in milliseconds to wait for the invitation to be accepted.

ourDid · string

Optional local DID to use when establishing the connection.

curl -X POST https://localhost:5000/v1/receive-invitation-url \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "invitationUrl": "https://agent.example.com?oob=eyJAdHlwZSI6...",
    "autoAcceptConnection": true,
    "autoAcceptInvitation": true
  }'

---

Get Credential List

Returns all credentials in the wallet, with optional filters.

threadId · string

Filter credentials by DIDComm thread ID.

connectionId · string

Filter credentials by the connection they were issued over.

state · string

Filter by credential exchange state (e.g., offer-received, credential-issued, done).

curl -X GET "https://localhost:5000/v1/credential?state=done" \
  -H "Authorization: Bearer <token>"

---

Get Credential by Record ID

Retrieves a specific credential record.

credentialRecordId · string · required

The credential exchange record ID.

curl -X GET https://localhost:5000/v1/credential/4e687079-273b-447b-b9dd-9589c84dc6dd \
  -H "Authorization: Bearer <token>"

---

Accept Credential Offer

Accepts a pending credential offer in the wallet.

credentialRecordId · string · required

The ID of the credential exchange record to accept.

autoAcceptCredential · string · required

Controls acceptance behavior. Enum: always, contentApproved, never.

credentialFormats · object · required

Credential format configuration object passed to the agent. Shape depends on the credential format (e.g., AnonCreds, JSON-LD).

comment · string

Optional comment to include with the acceptance.

curl -X POST https://localhost:5000/v1/accept-offer \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "credentialRecordId": "4e687079-273b-447b-b9dd-9589c84dc6dd",
    "autoAcceptCredential": "always",
    "credentialFormats": {},
    "comment": "Accepting the University degree credential"
  }'

---

Get Proof Presentations

Returns all proof presentations for the wallet, with an optional thread filter.

threadId · string

Optional DIDComm thread ID to filter proof presentations.

curl -X GET "https://localhost:5000/v1/proofs?threadId=abc123" \
  -H "Authorization: Bearer <token>"

---

Get Proof by ID

Retrieves a specific proof presentation record.

proofRecordId · string · required

The proof exchange record ID.

curl -X GET https://localhost:5000/v1/proofs/4e687079-273b-447b-b9dd-9589c84dc6dd \
  -H "Authorization: Bearer <token>"

---

Accept Proof Request

Submits a proof presentation in response to a verifier’s proof request.

proofRecordId · string (UUID) · required

The UUID of the proof exchange record to respond to.

filterByPresentationPreview · boolean

When true, filters the credentials presented to match the presentation preview. Default: false.

filterByNonRevocationRequirements · boolean

When true, filters credentials by non-revocation requirements. Default: false.

comment · string

Optional comment to include with the proof presentation.

curl -X POST https://localhost:5000/v1/proofs/accept-request \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "proofRecordId": "4e687079-273b-447b-b9dd-9589c84dc6dd",
    "filterByPresentationPreview": false,
    "filterByNonRevocationRequirements": false,
    "comment": "Presenting my degree credential"
  }'

---

Create DID

Creates a new Decentralized Identifier (DID) in the cloud wallet.

keyType · string · required

The cryptographic key type for the DID (e.g., ed25519).

method · string · required

The DID method (e.g., indy, key, web).

seed · string

Optional 32-character seed for deterministic DID generation. Spaces are not allowed.

network · string

Optional network identifier (e.g., bcovrin:testnet). Required for ledger-based DID methods.

domain · string

Optional domain for did:web (e.g., www.github.com).

role · string

Optional endorser role on the ledger (e.g., endorser).

privatekey · string

Optional private key in hex format (e.g., 651727dab6dfdbb4f18afff5f368d13b0dca41fd26bd5e1c7953457524d645e6).

endpoint · string

Optional DID endpoint URL.

did · string

Optional existing DID identifier to import (e.g., XzFjo1RTZ2h9UVFCnPUyaQ).

endorserDid · string

Optional endorser DID for ledger registration (e.g., did:indy:bcovrin:testnet:UEeW111G1tYo1nEkPwMcF).

curl -X POST https://localhost:5000/v1/did \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "keyType": "ed25519",
    "method": "indy",
    "seed": "000000000000000000000000000Seed1",
    "network": "bcovrin:testnet"
  }'

---

Get DID List

Returns all DIDs registered in the authenticated user’s cloud wallet.

curl -X GET https://localhost:5000/v1/did \
  -H "Authorization: Bearer <token>"

---

Send Basic Message

Sends a plaintext basic message to a connected party over an established DIDComm connection.

connectionId · string · required

The ID of the connection to send the message over.

content · string · required

The text content of the message.

curl -X POST https://localhost:5000/v1/basic-message/e315f30d-9beb-4068-aea4-abb5fe5eecb1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello! Your credential has been issued."
  }'

---

Get Basic Messages by Connection ID

Retrieves all basic messages exchanged on a specific connection.

connectionId · string · required

The ID of the connection whose messages to retrieve.

curl -X GET https://localhost:5000/v1/basic-message/e315f30d-9beb-4068-aea4-abb5fe5eecb1 \
  -H "Authorization: Bearer <token>"

---

Error Responses

Status	Meaning
400 Bad Request	Invalid request body or parameters (e.g., seed too long, invalid URL).
401 Unauthorized	JWT token missing or expired.
403 Forbidden	The user does not have permission to perform this action.
404 Not Found	The requested credential, proof, connection, or DID record does not exist.