Task 13: Verified Integration Log¶

Overview¶

This document logs every API call we have actually executed against the Velocity Network staging environment, with real requests, responses, and outcomes. This is the source of truth for what is confirmed working — use this when implementing backend services.

Last verified: 2026-04-15

Our Live Identity on Velocity Network Staging¶

Item	Value
Tenant ID (on CIH)	`69df3e9a1788f7af31e8edb1`
Organization DID	`did:web:stagingregistrar.velocitynetwork.foundation:d:curo-rec.test`
Organization Name	`Curo REC Test Organization`
CAO DID	`did:web:stagingregistrar.velocitynetwork.foundation:d:ilssi.org`
Primary Account (blockchain)	`0xC13c62b227c9Fde4Cd0f1B278a276fA411Fc2Add`
Logo URL	`https://stagingmedia.velocitynetwork.foundation/400x400-lwZVXpKa_jLkS2ClnS7Sm.jpeg`
Host URL	`https://stagingcih.velocitycareerlabs.io`
Service ID	`#vlc-credential-agent-operator-v-1-1`
Tenant Created At	`2026-04-15T07:30:34.947Z`

Keys Registered on Tenant (from keys.json)¶

Kid Fragment	Purpose	Algorithm	Key ID on CIH
`#vc-signing-key-1`	ISSUING_METADATA	SECP256K1	`69df3e9a1788f7af31e8edae`
`#eth-account-key-1`	DLT_TRANSACTIONS	SECP256K1	`69df3e9a1788f7af31e8edaf`
`#exchange-key-1`	EXCHANGES	SECP256K1	`69df3e9a1788f7af31e8edb0`

Not yet registered (available in keys.json): #vnf-permissioning-* (PERMISSIONING), #vnf-rotation-* (ROTATION)

Verified API Calls¶

1. ✅ Fetch Official Swagger Spec¶

curl -s "https://stagingcih.velocitycareerlabs.io/documentation/json"

Result: Full OpenAPI 3.0.3 spec returned. Title: "Credential Agent v2", Version: "2.0.0". Saved to: docs/requirements/tasks/POC/api-specs/cih-staging-official.json

2. ✅ List All Tenants¶

curl -H "Authorization: Bearer 01692F50514EDA42AFE52C0F526B1B2BF383B8631AF77B6340A3631EAAD712BC" \
     "https://stagingcih.velocitycareerlabs.io/operator/tenants/get"

Result (200 OK):

{
  "tenants": [
    {
      "id": "69df35ea1788f7af31e8edac",
      "createdAt": "2026-04-15T06:53:30.244Z",
      "did": "did:web:stagingregistrar.velocitynetwork.foundation:d:www.velocitycareerlabs-1.com",
      "name": "Velocity Career Labs",
      ...
    },
    {
      "id": "68f78bcc1e6659aee3b4f1ca",
      "createdAt": "2025-10-21T13:34:04.761Z",
      "did": "did:web:stagingregistrar.velocitynetwork.foundation:d:ilssi.org",
      "name": "International Lean Six Sigma Academy Limited",
      ...
    },
    {
      "id": "69df3e9a1788f7af31e8edb1",  ← OUR TENANT
      "createdAt": "2026-04-15T07:30:34.947Z",
      "did": "did:web:stagingregistrar.velocitynetwork.foundation:d:curo-rec.test",
      "name": "Curo REC Test Organization"
    }
  ],
  "requestId": "x8lnUGl4Jw"
}

3. ✅ Create Tenant (Our Curo REC)¶

curl -X POST -H "Authorization: Bearer 01692F50514EDA42AFE52C0F526B1B2BF383B8631AF77B6340A3631EAAD712BC" \
     -H "Content-Type: application/json" \
     "https://stagingcih.velocitycareerlabs.io/operator/tenants/create" \
     -d '{
       "tenant": {
         "did": "did:web:stagingregistrar.velocitynetwork.foundation:d:curo-rec.test",
         "name": "Curo REC Test Organization",
         "logo": "https://stagingmedia.velocitynetwork.foundation/400x400-lwZVXpKa_jLkS2ClnS7Sm.jpeg",
         "caoDid": "did:web:stagingregistrar.velocitynetwork.foundation:d:ilssi.org"
       },
       "keys": [
         {
           "purposes": ["ISSUING_METADATA"],
           "algorithm": "SECP256K1",
           "encoding": "hex",
           "kidFragment": "#vc-signing-key-1",
           "key": "b1f3af612d383feabf1489e565ef6225fc4fb5870a089ef5c67fb1b5154a7fcd"
         },
         {
           "purposes": ["DLT_TRANSACTIONS"],
           "algorithm": "SECP256K1",
           "encoding": "hex",
           "kidFragment": "#eth-account-key-1",
           "key": "25819ccef45d7a74c3dfa8cc9a0a840f41acf77d75d85c8d595b0f1747d28308"
         },
         {
           "purposes": ["EXCHANGES"],
           "algorithm": "SECP256K1",
           "encoding": "hex",
           "kidFragment": "#exchange-key-1",
           "key": "7556ef693e4174c62a7244fb4df206e2e7f30d7a013fbae860225646e760f17d"
         }
       ]
     }'

Result (200 OK):

{
  "tenant": {
    "id": "69df3e9a1788f7af31e8edb1",
    "createdAt": "2026-04-15T07:30:34.947Z",
    "updatedAt": "2026-04-15T07:30:34.947Z",
    "did": "did:web:stagingregistrar.velocitynetwork.foundation:d:curo-rec.test",
    "name": "Curo REC Test Organization",
    "logo": "https://stagingmedia.velocitynetwork.foundation/400x400-lwZVXpKa_jLkS2ClnS7Sm.jpeg",
    "hostUrl": "https://stagingcih.velocitycareerlabs.io",
    "primaryAccount": "0xC13c62b227c9Fde4Cd0f1B278a276fA411Fc2Add",
    "caoDid": "did:web:stagingregistrar.velocitynetwork.foundation:d:ilssi.org"
  },
  "keyMetadatas": [
    {
      "purposes": ["ISSUING_METADATA"],
      "encoding": "jwk",
      "kidFragment": "#vc-signing-key-1",
      "id": "69df3e9a1788f7af31e8edae",
      "createdAt": "2026-04-15T07:30:34.895Z",
      "algorithm": "SECP256K1"
    },
    {
      "purposes": ["DLT_TRANSACTIONS"],
      "encoding": "jwk",
      "kidFragment": "#eth-account-key-1",
      "id": "69df3e9a1788f7af31e8edaf",
      "createdAt": "2026-04-15T07:30:34.898Z",
      "algorithm": "SECP256K1"
    },
    {
      "purposes": ["EXCHANGES"],
      "encoding": "jwk",
      "kidFragment": "#exchange-key-1",
      "id": "69df3e9a1788f7af31e8edb0",
      "createdAt": "2026-04-15T07:30:34.900Z",
      "algorithm": "SECP256K1"
    }
  ],
  "requestId": "bfVTCLzAS_"
}

⚠️ DO NOT re-run this — tenant already exists. Duplicate creation will fail.

4. ✅ Get Registrar Verified Profile¶

curl -H "Authorization: Bearer <REGISTRAR_JWT>" \
     "https://stagingregistrar.velocitynetwork.foundation/api/v0.6/organizations/did:web:stagingregistrar.velocitynetwork.foundation:d:curo-rec.test/verified-profile"

Result (200 OK): Returns full organization profile as a Verifiable Credential (OrganizationBasicProfile-v1.0). Includes name, location, logo, website, contact emails, registration numbers, LinkedIn profile.

5. ✅ List Credential Types¶

curl -H "Authorization: Bearer <REGISTRAR_JWT>" \
     "https://stagingregistrar.velocitynetwork.foundation/api/v0.6/credential-types?pageSize=3"

Result (200 OK): Array of credential type objects with credentialType, schemaUrl, displayDescriptorUrls, recommended, issuerCategory, etc.

Failed Attempts (For Reference — What NOT to Do)¶

❌ Agent Operator API v0.8 endpoints¶

curl -X POST "https://stagingagent.velocitycareerlabs.io/operator-api/v0.8/tenants" ...

Result: 401 "Authorization token is invalid" — algorithm/signature errors regardless of token Reason: Older API, uses different auth. Not recommended by CTO. Do not use.

❌ CIH with `/operator-api/v0.8/` prefix¶

curl "https://stagingcih.velocitycareerlabs.io/operator-api/v0.8/tenants"

Result: 404 Not Found Reason: CIH uses /operator prefix, not /operator-api/v0.8.

❌ CIH with `/tenants/create` (no prefix)¶

curl "https://stagingcih.velocitycareerlabs.io/tenants/create"

Result: 404 Not Found Reason: Must include /operator prefix.

❌ Auth0 client_credentials grant with keys.json clientId¶

curl -X POST "https://vnf-staging.us.auth0.com/oauth/token" \
     -d '{"client_id": "eDu0gHWxto9hGbm2CKhCGbMrGCiucz7B", ...}'

Result: {"error": "access_denied", "error_description": "Service not enabled within domain"} Reason: Not needed — CIH uses Bearer token directly. The keys.json Auth0 credentials are for a different purpose.

❌ Tenant create without required fields¶

curl -X POST "https://stagingcih.velocitycareerlabs.io/operator/tenants/create" \
     -d '{"tenant": {"did": "..."}, "keys": [...]}'

Result: {"error": "Bad Request", "message": "body/tenant must have required property 'name'"} Reason: Must include name, logo, caoDid in the tenant object.

Lessons Learned¶

CIH API base URL is /operator, not /operator-api/v0.8/
Bearer token is used directly — no JWT exchange, no Auth0 flow needed
Required tenant fields: did, name, logo, caoDid
Two different APIs exist:
CIH (Credential Agent v2) at stagingcih.velocitycareerlabs.io/operator/* — USE THIS
Agent Operator API v0.8 at stagingagent.velocitycareerlabs.io/operator-api/v0.8/* — legacy, don't use
keys.json Auth0 credentials are NOT used for CIH API auth
Our keys (3 of 5) are registered on the tenant — PERMISSIONING and ROTATION keys not registered yet
Swagger docs live at /documentation (UI) and /documentation/json (spec) — always fetch fresh spec for truth

Next API Calls to Verify (Backend Implementation Priority)¶

These are the next endpoints to test as backend work progresses:

High Priority (P0 for POC)¶

POST /operator/issuer-services/create — Set up issuer service config
POST /operator/credentials/create — Issue single credential
POST /operator/credentials/create-many — Batch issue (CSV use case)
POST /operator/issue-links/refresh — Get claim deep links + QR codes
GET /operator/credentials/get?tenantId=69df3e9a1788f7af31e8edb1 — List credentials

Medium Priority¶

POST /operator/credentials/revoke — Revoke credentials
POST /operator/depots/create — Create depot
GET /operator/depots/get?tenantId=... — List depots

Drop 2 (Later)¶

POST /operator/presentations/check — Verify presentations

Backend Implementation Checklist (Next Steps)¶

Add confirmed values to .env:

VNF_CIH_API_URL=https://stagingcih.velocitycareerlabs.io
VNF_CIH_API_PATH_PREFIX=/operator
VNF_CIH_BEARER_TOKEN=01692F50514EDA42AFE52C0F526B1B2BF383B8631AF77B6340A3631EAAD712BC
VNF_TENANT_ID=69df3e9a1788f7af31e8edb1
VNF_ORGANIZATION_DID=did:web:stagingregistrar.velocitynetwork.foundation:d:curo-rec.test
VNF_CAO_DID=did:web:stagingregistrar.velocitynetwork.foundation:d:ilssi.org

Copy keys.json to app/backend/config/velocity-keys.json (gitignored)
Update velocity-registrar.service.ts:
Remove isPocMode mock logic
Change endpoint to ${cihApiUrl}/operator/tenants/create
Update payload structure to match verified request (above)
Create cih-api.service.ts (new):
Wraps CIH HTTP calls with Bearer token
Methods: createTenant, createCredential, createManyCredentials, refreshIssueLinks, revokeCredentials
Replace MockVCLProvider in vnf-sdk.service.ts:
Delete mock class entirely
Delegate to new cih-api.service.ts
Test end-to-end:
Create issuer service for our tenant
Issue a test credential for a sample employee
Get the issue link + QR code
Verify in frontend claim page

References¶

Official CIH spec: api-specs/cih-staging-official.json
Staging Integration Task
Consolidated API Reference
POC Application Flow
Swagger UI (live): https://stagingcih.velocitycareerlabs.io/documentation