Reference · Business Wallet API · v1

CodeB Business Wallet — REST API reference

Every endpoint below is served by business-wallet.ashx on the tenant hostname. All endpoints are HTTPS-only. Authentication is one of: none (public), OIDC bearer (admin), HMAC token (public but proof-signed), or invite HMAC (public, invite-signed).

Wallet lifecycle

list-wallets response

{
  "tenant": "phone.aloaha.com",
  "count": 2,
  "wallets": [
    { "id": "acme-ltd",
      "name": "Acme Ltd",
      "reg": "C-99999",
      "juris": "MT",
      "vat": "MT12345678",
      "did": "did:web:phone.aloaha.com:business-wallets:acme-ltd",
      "did_doc_url": "https://phone.aloaha.com/business-wallets/acme-ltd/did.json",
      "url": "https://phone.aloaha.com/web-business-wallet.html?bw=acme-ltd",
      "wallet_id": "urn:aloaha:web-wallet:xyz9YtGL8W...",
      "created": "2026-08-07T09:12:44Z" }
  ]
}

create-wallet request

POST /business-wallet.ashx?action=create-wallet&slug=acme-ltd
Authorization: Bearer <oidc-token>
Content-Type: application/json

{ "name": "Acme Ltd",
  "reg":  "C-99999",
  "juris":"MT",
  "vat":  "MT12345678",
  "addr": "Level 3, Sky Parks, Malta" }

State + directory

Documents (PAdES-B-B inline signer)

External sharing (HMAC + invites)

Wallet-Instance-Attestation + credential issuance

Verifiable-credential vault (company-held VCs)

Registry push (external submitters)

Banks, business registries, notaries push documents into a wallet without needing an OIDC account. Three auth methods:

1. Company DID — X-Push-Auth: company + X-Push-Did: did:web:<X> where X is in this tenant's trust list. Actor logged as registry:<did>.
2. Personal PID — X-Push-Auth: pid + X-Push-Vp: <SD-JWT VC>. VP verified via /vcdm.ashx?action=verify. Actor logged as pid:<subject>.
3. OIDC Bearer — standard admin token. Actor logged as oidc:<email>.

Encrypted backup + presentation scaffolding

Audit

AI Agent Identity

Any employee whose role is agent becomes a machine identity in the wallet. Each agent gets a fragment DID under the wallet, has a stored capability list and a maximum token TTL, and can be issued short-lived ES256 capability tokens signed by the tenant issuer. Downstream services fetch the public agent manifest to learn what the agent is + who owns it, then call verify-agent-token on any received token. See the explainer at ai-agent-identity.html.

Agent-aware add-employee body

POST /business-wallet.ashx?action=add-employee&bw=<cid>
Authorization: Bearer <OIDC token>
Content-Type: application/json

{
  "name": "invoice-triage",
  "role": "agent",
  "agent_model":         "large-model",
  "agent_provider_hint": "acme-agents",
  "agent_purpose":       "Reads incoming invoices and files them",
  "agent_capabilities":  ["list-docs","download-doc","verify-vc","file-invoice"],
  "agent_max_ttl_sec":   3600
}

Non-agent roles that carry any agent_* field are rejected with 400 agent_fields_only_valid_for_agent_role. Capability entries limited to 64 chars, [a-zA-Z0-9._-]. TTL clamped to 60–86400 s.

Endpoints

mint-agent-token response

{
  "ok": true,
  "token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImNvZGViLWFnZW50LXRva2VuK2p3dCJ9....",
  "exp": 1786320000,
  "iat": 1786316400,
  "agent_did": "did:web:tenant.example:business-wallets:acme-ltd#agent-e_abc123",
  "owner_did": "did:web:tenant.example:business-wallets:acme-ltd",
  "scope": ["list-docs","download-doc","verify-vc"],
  "typ": "codeb-agent-token+jwt",
  "ttl_sec": 3600
}

agent-manifest response

{
  "id": "e_abc123",
  "name": "invoice-triage",
  "role": "agent",
  "agent_model": "large-model",
  "agent_provider_hint": "acme-agents",
  "agent_purpose": "Reads incoming invoices and files them",
  "agent_capabilities": ["list-docs","download-doc","verify-vc"],
  "agent_max_ttl_sec": 3600,
  "agent_active": true,
  "agent_did": "did:web:tenant.example:business-wallets:acme-ltd#agent-e_abc123",
  "owner_did": "did:web:tenant.example:business-wallets:acme-ltd",
  "issuer": "did:web:tenant.example:business-wallets:acme-ltd",
  "manifest_url": "https://tenant.example/business-wallet.ashx?action=agent-manifest&bw=acme-ltd&emp=e_abc123",
  "did_doc_url":  "https://tenant.example/business-wallets/acme-ltd/did.json",
  "token_type": "codeb-agent-token+jwt",
  "issuer_key": { "kty":"EC","crv":"P-256","x":"...","y":"...","use":"sig","alg":"ES256" },
  "revocation": {
    "type": "BitstringStatusList",
    "url": "https://tenant.example/business-wallet.ashx?action=agent-status-list&bw=acme-ltd"
  }
}

verify-agent-token response

{
  "verified": true,
  "reason": "ok",
  "agent_did": "did:web:...#agent-e_abc123",
  "owner_did": "did:web:...",
  "iss": "did:web:...",
  "exp": 1786320000,
  "scope": ["list-docs","download-doc"],
  "typ": "codeb-agent-token+jwt"
}

Failure reasons: not_compact_jws, malformed_segment:*, unsupported_alg:*, token_expired, iss_not_this_tenant, iss_bad_companyId, agent_did_missing_fragment, issuer_pfx_missing, bad_signature, agent_not_found, employee_not_agent, agent_deactivated. Verifier never leaks internal state on failure — every reason is a stable machine-readable slug.

Sibling endpoints

SIP softphone provisioning (sipprov.ashx)

Short-TTL HMAC token that resolves to a Zoiper XML, Linphone .rc, or JSON provisioning payload. Prevents plaintext SIP passwords in QR codes.

Standards

OID4VP 1.0 FINAL · OID4VCI Draft-15 · SD-JWT VC draft-07 · W3C VCDM 2.0 (JOSE envelope) · W3C DID Core 1.0 · W3C Bitstring Status List v1.0 · ETSI TS 119 602 Trusted List · ETSI EN 319 102-1 PAdES-B-B · HAIP §5.11 Wallet Attestation · European Digital Identity Wallet (eIDAS 2.0, ARF 3.0).