Skip to main content
The cloud wallet is a managed wallet service in CREDEBL designed for credential holders — individuals or systems that receive, store, and present verifiable credentials. Unlike an organization wallet (which is provisioned alongside an agent for issuance and verification), the cloud wallet is a lightweight, user-scoped wallet managed entirely by the CREDEBL platform.

​
Org wallet vs. cloud wallet

Organization WalletCloud Wallet
PurposeIssue credentials, request proofsHold and present credentials
User typeOrganizations (issuers, verifiers)Individual holders
DID scopeTied to the organization’s agentTied to the individual user
ProvisioningAgent spin-up with ledger registrationLightweight wallet creation
Wallet typeCLOUD_BASE_WALLET or CLOUD_SUB_WALLETCLOUD_SUB_WALLET
The CloudWalletType enum defines two wallet types:
  • CLOUD_BASE_WALLET — the base wallet configured by a platform operator
  • CLOUD_SUB_WALLET — an individual user’s wallet derived from the base wallet

​
Cloud wallet capabilities

Receive credentials

Accept credential offers from issuers via OOB invitation URLs or by accepting offers directly with a credential record ID.

Store credentials

Credentials received and accepted are stored in the wallet and can be listed and retrieved by credential record ID.

Present proofs

Respond to proof requests from verifiers by submitting a proof presentation from stored credentials.

Manage connections

Create connection invitations, receive invitations via URL, and manage existing connections by ID.

Manage DIDs

Create DIDs within the cloud wallet and list all DIDs associated with the wallet.

Basic messaging

Send and receive basic DIDComm messages over existing connections.

​
Creating a cloud wallet

Before creating individual user wallets, a platform operator must configure the base wallet. The base wallet provides the cloud infrastructure that individual (sub) wallets are derived from.

​
Configure the base wallet

POST /configure/base-wallet
Authorization: Bearer <token>

{
  "walletKey": "<wallet-encryption-key>",
  "connectionImageUrl": "https://example.com/agent-avatar.png"
}

​
Create a user wallet

Each authenticated user can create their own cloud wallet: 
POST /create-wallet
Authorization: Bearer <token>

{
  "label": "My Credential Wallet",
  "connectionImageUrl": "https://picsum.photos/200"
}
The label field identifies the wallet in DIDComm connections. The authenticated user’s email and ID are automatically bound to the wallet.
The cloud wallet endpoints use the UserRoleGuard, which requires the user to have the HOLDER user role (UserRole.HOLDER). A user with DEFAULT_USER role must be promoted to HOLDER before creating a cloud wallet.

​
Receiving a credential offer

When an issuer sends a credential via an OOB invitation URL (for example, from a QR code or email link), the holder receives it by submitting the URL to their cloud wallet:
1

Receive the invitation URL

Submit the OOB invitation URL to create a connection:
POST /receive-invitation-url
Authorization: Bearer <token>

{
  "invitationUrl": "https://issuer.example.com?oob=eyJAdHlwZSI6...",
  "autoAcceptConnection": true,
  "autoAcceptInvitation": true
}
Optional parameters control connection reuse (reuseConnection), timeout (acceptInvitationTimeoutMs), and the local DID to use for the connection (ourDid).
2

Accept the credential offer

Once the connection is established and the credential offer arrives, accept it:
POST /accept-offer
Authorization: Bearer <token>

{
  "credentialRecordId": "<credential-record-id>",
  "autoAcceptCredential": "always",
  "credentialFormats": {}
}
The autoAcceptCredential field accepts always, contentApproved, or never (from the AutoAccept enum).
3

Retrieve the stored credential

List all credentials in the wallet or retrieve a specific one by record ID:
GET /credential
GET /credential/:credentialRecordId
Query parameters for listing: threadId, connectionId, state.

​
Responding to a proof request

When a verifier sends a proof request to the holder’s cloud wallet:
1

View the proof request

List all proof presentations or retrieve a specific one by ID:
GET /proofs
GET /proofs/:proofRecordId
Optional: filter by threadId.
2

Accept and send the proof

Submit a proof presentation in response to the request:
POST /proofs/accept-request
Authorization: Bearer <token>

{
  "proofRecordId": "<proof-record-id>",
  "filterByPresentationPreview": true,
  "comment": "Presenting employee credentials"
}

​
Managing connections

The cloud wallet maintains a list of all DIDComm connections established with issuers and verifiers.

​
Create a connection invitation

Generate a connection invitation that another agent can accept: 
POST /connections/invitation
Authorization: Bearer <token>

​
List all connections

GET /connections
Optional query parameters: outOfBandId, alias, myDid, theirDid, theirLabel.

​
Get a specific connection

GET /connection/:connectionId

​
Managing DIDs in the cloud wallet

​
Create a DID

Create a DID within the cloud wallet using any supported method: 
POST /did
Authorization: Bearer <token>

{
  "method": "key",
  "keyType": "ed25519"
}
For did:indy, add the network field (e.g., "bcovrin:testnet"). For did:web, add the domain field. An optional 32-character seed can be provided to generate a deterministic key pair. Spaces are not allowed in the seed value.

​
List DIDs

GET /did
Returns all DIDs registered in the cloud wallet.

​
Basic messaging

The cloud wallet supports DIDComm basic messages for communication over established connections.

​
Send a message

POST /basic-message/:connectionId
Authorization: Bearer <token>

{
  "content": "Hello from my cloud wallet"
}

​
Retrieve messages

GET /basic-message/:connectionId
Returns all basic messages exchanged over the specified connection.

Build docs developers (and LLMs) love

Get started for freeTalk to us