Velocity Network Foundation APIs for REC Verifiable Credentialing Platform

This document outlines the Velocity Network Foundation (VNF) APIs required for implementing the REC Verifiable Credentialing Platform, their purposes, key endpoints, and how they map to the application requirements.

Overview of Required APIs

The REC Verifiable Credentialing Platform needs to integrate with the following Velocity Network Foundation APIs:

1. Registrar API - For organization registration and management
2. Agent Operator API - For credential issuance and verification
3. Push Gateway API - For notifications and credential offers
4. CIH Operator API - For credential issuance hub operations
5. Agent Credential Holder API - For credential holder operations

Mock Server URLs for Development

API	Mock Server URL
Registrar API	https://stoplight.io/mocks/velocitycareerlabs/registrar-api/27695925
Agent Operator API	https://stoplight.io/mocks/velocitycareerlabs/agent-services-api/9088762
Push Gateway API	https://stoplight.io/mocks/velocitycareerlabs/push-gateway-api/66945276
CIH Operator API	https://stoplight.io/mocks/velocitycareerlabs/cih-operator-api/454985889
Agent Credential Holder API	https://stoplight.io/mocks/velocitycareerlabs/velocity-network-exchange-protocol/219930116

Detailed API Descriptions and Key Endpoints

1. Registrar API

Purpose: Manages organization registration and verification on the Velocity Network.

Key Endpoints:

• POST /organizations - Register a new organization
• GET /organizations/{id} - Get organization details
• PUT /organizations/{id} - Update organization details
• GET /organizations/{id}/status - Check organization verification status
• POST /organizations/{id}/verify - Submit organization for verification

Application Use Cases: - Organization onboarding (F-OO-01: Organization Registration) - Know Your Business (KYB) verification (F-OO-02: Business Verification) - Organization profile management (F-OO-03: Company Profile Management)

2. Agent Operator API

Purpose: Handles credential issuance, verification, and management operations.

Key Endpoints:

• POST /credentials/issue - Issue a new credential
• GET /credentials/{id} - Get credential details
• PUT /credentials/{id}/status - Update credential status (revoke, suspend)
• POST /credentials/verify - Verify a credential
• GET /issuers - Get list of registered issuers
• GET /verifiers - Get list of registered verifiers

Application Use Cases: - Credential issuance (F-CI-03: Velocity Credential Agent Integration) - Credential verification (F-CV-01: Verification Process Integration) - Credential status management

3. Push Gateway API

Purpose: Manages notifications and credential offers to credential holders.

Key Endpoints:

• POST /notifications - Send a notification
• POST /offers - Send a credential offer
• GET /offers/{id}/status - Check offer status
• POST /disclosure-requests - Send a disclosure request
• GET /disclosure-requests/{id}/status - Check disclosure request status

Application Use Cases: - Credential offer notifications (F-CI-04: Candidate Notification) - Disclosure request notifications (F-CD-03: Disclosure Request Delivery) - Email and notification templates (F-CI-05: Email and Landing Page Configuration)

4. CIH Operator API

Purpose: Manages the Credential Issuance Hub operations for batch processing and advanced issuance scenarios.

Key Endpoints:

• POST /batch/upload - Upload batch credential data
• GET /batch/{id}/status - Check batch processing status
• GET /batch/{id}/results - Get batch processing results
• POST /templates - Create credential template
• GET /templates - List credential templates
• POST /batch/process - Process batch using template

Application Use Cases: - Batch credential issuance (F-CI-02: Batch Credential Issuance) - CSV upload and processing - Credential template management

5. Agent Credential Holder API

Purpose: Manages interactions with credential holders, including credential sharing and disclosure.

Key Endpoints:

• POST /holders/{id}/credentials - Add credential to holder's wallet
• GET /holders/{id}/credentials - List holder's credentials
• POST /holders/{id}/share - Share credentials
• GET /disclosures/{id} - Get disclosure details
• POST /disclosures/{id}/accept - Accept disclosure request
• POST /disclosures/{id}/reject - Reject disclosure request

Application Use Cases: - Credential disclosure (F-CD-01: Disclosure Request Configuration) - Credential sharing - Verification policy enforcement (F-CD-02: Verification Policy Configuration)

API Usage by Feature

Organization Onboarding

1. Organization Registration (F-OO-01)
2. Registrar API: POST /organizations

3. Registrar API: GET /organizations/{id}/status

4. Business Verification (F-OO-02)

5. Registrar API: POST /organizations/{id}/verify

6. Registrar API: GET /organizations/{id}/status

7. Company Profile Management (F-OO-03)

8. Registrar API: PUT /organizations/{id}
9. Registrar API: GET /organizations/{id}

Credential Issuance

1. Manual Credential Issuance (F-CI-01)
2. Agent Operator API: POST /credentials/issue

3. Push Gateway API: POST /offers

4. Batch Credential Issuance (F-CI-02)

5. CIH Operator API: POST /batch/upload
6. CIH Operator API: POST /batch/process

7. CIH Operator API: GET /batch/{id}/status

8. Velocity Credential Agent Integration (F-CI-03)

9. Agent Operator API: Various endpoints

10. Registrar API: Various endpoints

11. Candidate Notification (F-CI-04)

12. Push Gateway API: POST /notifications
13. Push Gateway API: POST /offers

Credential Disclosure

1. Disclosure Request Configuration (F-CD-01)
2. Agent Credential Holder API: POST /disclosures

3. Push Gateway API: POST /disclosure-requests

4. Verification Policy Configuration (F-CD-02)

5. Agent Operator API: POST /policies

6. Agent Credential Holder API: POST /disclosures

7. Disclosure Request Delivery (F-CD-03)

8. Push Gateway API: POST /disclosure-requests
9. Push Gateway API: GET /disclosure-requests/{id}/status

Credential Verification

1. Verification Process Integration (F-CV-01)
2. Agent Operator API: POST /credentials/verify

3. Agent Credential Holder API: GET /disclosures/{id}

4. Verification Results Display (F-CV-02)

5. Agent Operator API: POST /credentials/verify

6. Agent Operator API: GET /verifications/{id}

7. Verification Report Generation (F-CV-03)

8. Agent Operator API: GET /verifications/{id}/report

9. Universal Credential Verification (F-CV-04)

10. Agent Operator API: POST /credentials/verify
11. Agent Credential Holder API: GET /disclosures/{id}

Testing Approach

To test these APIs with the Velocity site:

1. Access the Stoplight Mock Servers:
2. Use the provided mock server URLs to explore the API documentation

3. Test API endpoints directly through the Stoplight interface

4. Test Key Workflows:

5. Organization registration and verification
6. Credential issuance (manual and batch)
7. Credential verification

8. Disclosure requests

9. Validate Response Formats:

10. Ensure the response formats match what your application expects

11. Document any discrepancies or additional fields

12. Test Error Scenarios:

13. Invalid requests
14. Missing required fields
15. Authentication failures

Next Steps

1. Explore the API documentation on Stoplight for each API
2. Test key endpoints using the mock servers
3. Document the exact request/response formats needed for implementation
4. Implement API integration services in the backend
5. Create unit tests for API interactions

Resources

• Velocity Network Foundation
• VNF Wallet SDK for Node.js
• Stoplight API Documentation (available through the mock server URLs)