Consolidated Velocity Network API Reference¶

Overview¶

Single source of truth for all Velocity Network API endpoints needed for the REC platform. Compiled from OpenAPI specs, Postman collection, SDK source, CTO communications, and verified live API calls (2026-04-15).

Authentication Status: CONFIRMED WORKING (2026-04-15). CIH API is at https://stagingcih.velocitycareerlabs.io with path prefix /operator and the provided Bearer token.

Environments¶

Primary APIs for POC (Confirmed Working)¶

API	Staging URL	Purpose
CIH (Credential Agent v2)	`https://stagingcih.velocitycareerlabs.io`	Tenant creation, credential issuance, verification
Registrar API	`https://stagingregistrar.velocitynetwork.foundation/api/v0.6`	Organization profiles, credential types, schemas

Deprecated / Not Used¶

API	URL	Reason
Agent Operator API v0.8	`https://stagingagent.velocitycareerlabs.io/operator-api/v0.8`	Older path — CIH v2 is the replacement
Stoplight Mock (Registrar)	`https://stoplight.io/mocks/velocitycareerlabs/registrar-api/*`	Mock — real staging now available
Stoplight Mock (Agent)	`https://stoplight.io/mocks/velocitycareerlabs/agent-services-api/*`	Mock — real staging now available

Our Credentials¶

Item	Value
Organization DID	`did:web:stagingregistrar.velocitynetwork.foundation:d:curo-rec.test`
Tenant ID (on CIH)	`69df3e9a1788f7af31e8edb1`
CAO DID	`did:web:stagingregistrar.velocitynetwork.foundation:d:ilssi.org`
Service ID	`#vlc-credential-agent-operator-v-1-1`
Org Name	`Curo REC Test Organization`
Primary Account	`0xC13c62b227c9Fde4Cd0f1B278a276fA411Fc2Add` (blockchain)
CIH Bearer Token	`01692F50514EDA42AFE52C0F526B1B2BF383B8631AF77B6340A3631EAAD712BC`
Keys	5 SECP256K1 keys in `keys.json` (3 registered on tenant)
Registrar JWT source	`stagingauth.velocitynetwork.foundation` (RS256, from dashboard)

Not Needed For API Auth¶

Item	Note
Auth0 Client ID `eDu0gHWxto9hGbm2CKhCGbMrGCiucz7B`	Part of keys.json but not used for CIH API auth
Auth0 Client Secret	Part of keys.json but not used for CIH API auth

Authentication (CONFIRMED WORKING)¶

CIH API Authentication¶

Authorization: Bearer 01692F50514EDA42AFE52C0F526B1B2BF383B8631AF77B6340A3631EAAD712BC

Direct static Bearer token — no JWT exchange, no Auth0 flow needed. Use this exact header on all /operator/* endpoints.

Registrar API Authentication¶

Authorization: Bearer <JWT from stagingregistrarapp dashboard>

RS256 JWT obtained by logging into https://stagingregistrarapp.velocitycareerlabs.com and retrieving the session token. Audience: registrar.velocitynetwork.foundation.

Verified Test (2026-04-15)¶

# List tenants - returns 200 OK with array of tenants
curl -H "Authorization: Bearer 01692F50514EDA42AFE52C0F526B1B2BF383B8631AF77B6340A3631EAAD712BC" \
     "https://stagingcih.velocitycareerlabs.io/operator/tenants/get"

API 1: Registrar API¶

Base: https://stagingregistrar.velocitynetwork.foundation/api/v0.6 Auth: Bearer JWT from stagingauth.velocitynetwork.foundation Source: api-specs/registrar.v1.json Status: CONFIRMED WORKING

Organization Management¶

Method	Endpoint	Description	POC?
`POST`	`/organizations/full`	Create org (returns DID + keys + authClients)	Done via UI
`GET`	`/organizations/full`	List all organizations	No
`GET`	`/organizations/full/{did}`	Get org details by DID	Yes
`PUT`	`/organizations/profile/{did}`	Update org profile	No
`DELETE`	`/organizations/{did}`	Soft delete org	No
`GET`	`/organizations/{did}/verified-profile`	Get verified profile	Yes

Services (Issuer/Verifier Setup)¶

Method	Endpoint	Description	POC?
`POST`	`/organizations/{did}/services`	Add service (issuer/verifier)	Done via UI
`GET`	`/organizations/{did}/services`	List services	No
`PUT`	`/organizations/{did}/services/{serviceId}`	Update service	No
`DELETE`	`/organizations/{did}/services/{serviceId}`	Delete service	No
`POST`	`/organizations/{did}/activate-services`	Activate services	Future
`POST`	`/organizations/{did}/deactivate-services`	Deactivate services	No

Keys¶

Method	Endpoint	Description	POC?
`POST`	`/organizations/{did}/keys`	Add a key	No (have keys)
`GET`	`/organizations/{did}/keys/{kid}`	Get key details	No
`DELETE`	`/organizations/{did}/keys/{kid}`	Delete a key	No

Credential Types & Schemas¶

Method	Endpoint	Description	POC?
`GET`	`/credential-types`	List all credential types	Yes
`GET`	`/credential-types/{id}`	Get specific type	Yes
`GET`	`/schemas/{schemaName}`	Get JSON schema	Yes
`GET`	`/schemas/{schemaName}.schema.json`	Get schema by filename	Yes
`POST`	`/schemas/{schemaName}/validate`	Validate credential subject	Yes
`GET`	`/form-schemas/{name}.form-schema.json`	Get form schema for UI	Yes

Search & Resolution¶

Method	Endpoint	Description	POC?
`GET`	`/organizations/search-profiles`	Search org profiles	Yes
`GET`	`/resolve-did/{did}`	Resolve DID to DID document	Yes
`GET`	`/resolve-kid/{kid}`	Resolve key ID to public key	Yes
`GET`	`/service-types`	Get available service types	No

Other¶

Method	Endpoint	Description	POC?
`POST`	`/organizations/{did}/invitations`	Create admin invitation	Future
`GET`	`/organizations/{did}/invitations`	List invitations	No
`POST`	`/test-secure-webhook-url`	Test webhook URL	No
`POST`	`/setup_image_upload`	Setup image upload	No

API 2: CIH (Credential Agent v2) API¶

Base: https://stagingcih.velocitycareerlabs.io/operator Auth: Bearer 01692F50514EDA42AFE52C0F526B1B2BF383B8631AF77B6340A3631EAAD712BC Source: api-specs/cih-staging-official.json (fetched from /documentation/json) Status: CONFIRMED WORKING (2026-04-15) API Version: 2.0.0

Tenants (Phase 1 — Organization Setup)¶

Method	Endpoint	Description	POC?	Priority	Status
`POST`	`/operator/tenants/create`	Create tenant	YES	P0	✅ VERIFIED
`GET`	`/operator/tenants/get`	List all tenants	Yes	P1	✅ VERIFIED
`POST`	`/operator/tenants/delete`	Delete tenant	No	—	—

Verified Request — Create Tenant (POST /operator/tenants/create):

{
  "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": "<hex key from keys.json>"
    },
    {
      "purposes": ["DLT_TRANSACTIONS"],
      "algorithm": "SECP256K1",
      "encoding": "hex",
      "kidFragment": "#eth-account-key-1",
      "key": "<hex key from keys.json>"
    },
    {
      "purposes": ["EXCHANGES"],
      "algorithm": "SECP256K1",
      "encoding": "hex",
      "kidFragment": "#exchange-key-1",
      "key": "<hex key from keys.json>"
    }
  ]
}

Required tenant fields: did, name, logo, caoDid

Verified Response — Create Tenant (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"
    }
  ],
  "requestId": "bfVTCLzAS_"
}

Note: Our tenant is already created (ID 69df3e9a1788f7af31e8edb1). Do not re-run create tenant — it will fail as duplicate.

Issuer Services (Phase 2 — Configure Issuance)¶

Method	Endpoint	Description	POC?	Priority
`POST`	`/operator/issuer-services/create`	Create issuer service	YES	P0
`GET`	`/operator/issuer-services/get`	List issuer services	Yes	P1
`POST`	`/operator/issuer-services/update`	Update issuer service	No	—
`POST`	`/operator/issuer-services/delete`	Delete issuer service	No	—

Auth modes supported: verifiable_presentation, preauth, webhook

Depots (Credential Templates / Batches)¶

Method	Endpoint	Description	POC?	Priority
`POST`	`/operator/depots/create`	Create depot (single)	Yes	P1
`GET`	`/operator/depots/get`	List depots	Yes	P1
`POST`	`/operator/depots/delete`	Delete depot	No	—

Credentials (Phase 2 — Core Issuance)¶

Method	Endpoint	Description	POC?	Priority
`POST`	`/operator/credentials/create`	Issue single credential	YES	P0
`POST`	`/operator/credentials/create-many`	Batch issue credentials (CSV use case)	YES	P0
`GET`	`/operator/credentials/get`	List issued credentials	Yes	P0
`POST`	`/operator/credentials/delete`	Delete credential	No	—
`POST`	`/operator/credentials/revoke`	Revoke credential(s)	Yes	P1

Issue Links (Phase 2 — Claim URLs)¶

Method	Endpoint	Description	POC?	Priority
`POST`	`/operator/issue-links/refresh`	Get/refresh claim deep links	YES	P0

Presentations (Drop 2 — Verification)¶

Method	Endpoint	Description	POC?
`POST`	`/operator/presentations/check`	Verify presentation	No (Drop 2)

Public/Holder Endpoints (Used by Wallet, Not by Us)¶

Method	Endpoint	Description
`GET`	`/.well-known/oauth-authorization-server/r/{tenantId}`	OAuth discovery for wallet
`GET`	`/.well-known/openid-credential-issuer/r/{tenantId}`	OpenID credential issuer metadata
`GET`	`/app-redirect`	Wallet deep-link redirect
`POST`	`/r/{tenantId}/oauth/token`	OAuth token endpoint (for wallets)
`POST`	`/r/{tenantId}/openid4vc/credential`	OpenID4VC credential endpoint
`POST`	`/r/{tenantId}/openid4vc/nonce`	OpenID4VC nonce
`POST`	`/r/{tenantId}/openid4vc/notification`	OpenID4VC notification
`POST`	`/vn-api/r/{tenantId}/authenticate`	Velocity Network holder auth
`POST`	`/vn-api/r/{tenantId}/credential-offers`	Get credential offers (holder)
`GET`	`/vn-api/r/{tenantId}/get-credential-manifest`	Get credential manifest (holder)
`POST`	`/vn-api/r/{tenantId}/issue-credentials`	Issue credentials (holder flow)

These are called by the holder's wallet application, NOT by our backend. We don't need to implement calls to these.

POC Critical Path — CIH API Call Sequence¶

PHASE 1: TENANT SETUP (One-time — ALREADY DONE 2026-04-15)
───────────────────────────────────────────────────────────
✅ POST /operator/tenants/create
   Body: { tenant: { did, name, logo, caoDid }, keys: [...] }
   Response: { tenant: { id, did, ... }, keyMetadatas: [...] }

   → Tenant ID stored: 69df3e9a1788f7af31e8edb1
   → No need to re-run; tenant already exists.

PHASE 2: CONFIGURE ISSUER SERVICE (One-time per credential type)
─────────────────────────────────────────────────────────────────
1. POST /operator/issuer-services/create
   Body: {
     tenantId: "69df3e9a1788f7af31e8edb1",
     service: {
       velocityNetworkServiceId: "#vlc-credential-agent-operator-v-1-1",
       authMethods: ["verifiable_presentation"],
       authMode: "internal",
       termsUrl: "https://curo-rec.test/terms",
       disclosureRequest: {
         types: [{ type: "EmailV1.1" }],
         purpose: "Issuing employment credential",
         retentionPeriod: "P30D"
       }
     }
   }

PHASE 3: CREDENTIAL ISSUANCE (Per employee or batch)
─────────────────────────────────────────────────────
SINGLE:
2a. POST /operator/credentials/create
    Body: { tenantId, credential: { type, credentialSubject, ... } }
    Response: { credential: { id, ... }, requestId }

BATCH (CSV use case):
2b. POST /operator/credentials/create-many
    Body: { tenantId, credentials: [...] }
    Response: { credentials: [...], requestId }

PHASE 4: GET CLAIM LINKS
─────────────────────────
3. POST /operator/issue-links/refresh
   Body: { tenantId, ... }
   Response: { issueLinks: [{ url, qrCode, credentialId }] }

PHASE 5: SEND TO EMPLOYEE
──────────────────────────
4. Send email with deep-link URL + QR code (our email system)

TRACKING & MANAGEMENT
──────────────────────
5. GET /operator/credentials/get → List all credentials + status
6. POST /operator/credentials/revoke → Revoke if needed

Key Advantages of CIH over Old Agent Operator API¶

Old (Agent v0.8)	New (CIH v2)
5 separate calls per credential	1 call for batch of N credentials
Manual exchange → offer → complete flow	Simple `create-many`
Deep link per exchange	Deep links via `issue-links/refresh`
Session tokens to manage	Stateless operations

Employee → Credential Subject Mapping¶

Employee Entity Field	CredentialSubject Field	Required
`organization.organizationDid`	`company`	Yes
`organization.name`	`companyName.localized.en`	Yes
`jobTitle`	`title.localized.en`	Yes
`startDate` (extract month/year)	`startMonthYear.month` / `startMonthYear.year`	Yes
`endDate` (extract month/year)	`endMonthYear.month` / `endMonthYear.year`	Yes (for past)
`workLocation` → country code	`location.countryCode`	Yes
`workLocation` → region code	`location.regionCode`	No
`department` + notes	`description.localized.en`	No

Credential Types for POC¶

Type	Schema	POC?
`EmploymentPastV1.1`	`employment-past-v1.1.schema.json`	YES (Primary)
`EmploymentCurrentV1.1`	`employment-current-v1.1.schema.json`	Future
`EmailV1.0`	`email-v1.0.schema.json`	For identification
`PhoneV1.0`	`phone-v1.0.schema.json`	For identification

Schema URL pattern: https://stagingregistrar.velocitynetwork.foundation/schemas/<name>.schema.json

Deep Link Format¶

Mobile wallet:

velocity-network-testnet://issue?request_uri=<encoded-url>&issuerDid=<did>

HTTPS fallback (from /deep-link endpoint):

https://stagingagent.velocitycareerlabs.io/api/holder/v0.6/org/<did>/issue/get-credential-manifest?id=<id>&credential_types=EmploymentPastV1.1

Files Consolidated Into This Reference¶

File	What It Contained
`Velocity_POC_Postman_Collection.json`	Mock Registrar + placeholder Agent endpoints
`docs/techstack/velocity-network-apis.md`	All 5 VNF API mock URLs + endpoints
`vcl_api_spec.txt`	Issuer, verifier, schema, batch endpoints
`docs/requirements/tasks/POC/api-specs/agent-api.v1.json`	Agent Operator API OpenAPI spec
`docs/requirements/tasks/POC/api-specs/registrar.v1.json`	Registrar API OpenAPI spec
`app/backend/docs/velocity-registrar-api-usage.md`	Internal REC platform API docs
`docs/requirements/tasks/velocity-registrar-api-integration.md`	Registrar integration DTOs
`docs/requirements/tasks/POC/task-vnf-tenant-registration-api.md`	Tenant creation task
`vnf-wallet-sdk-nodejs-main/packages/sdk/src/impl/data/repositories/Urls.ts`	SDK URL patterns
`vnf-wallet-sdk-nodejs-main/packages/sample-app/src/Constants.ts`	Deep links + test JWTs

Status Legend¶

Symbol	Meaning
P0	Must work for POC demo
YES	Needed for POC
No	Not needed for POC (Drop 1 Beta / Drop 2 / Post-MVP)
🔐	Authentication not yet resolved
Done via UI	Already completed through Velocity Registrar web interface