the_order/docs/api/identity-service.md

Identity Service API Documentation

Overview

The Identity Service provides comprehensive identity management, verifiable credential issuance, and authentication capabilities for The Order platform.

Base URL: http://localhost:4002 (development)
API Version: 1.0.0

Authentication

Most endpoints require authentication via JWT tokens or DID-based authentication. Include the token in the Authorization header:

Authorization: Bearer <token>

Endpoints

Health Check

GET /health

Check service health status.

Response:

{
  "status": "ok",
  "service": "identity",
  "database": "connected",
  "kms": "available"
}

---

Verifiable Credentials

POST /vc/issue

Issue a verifiable credential.

Authentication: Required (JWT, roles: admin, issuer)

Request Body:

{
  "subject": "did:web:subject.com",
  "credentialSubject": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "expirationDate": "2025-12-31T23:59:59Z"
}

Response (200):

{
  "credential": {
    "id": "credential-id",
    "type": ["VerifiableCredential", "IdentityCredential"],
    "issuer": "did:web:issuer.com",
    "subject": "did:web:subject.com",
    "credentialSubject": { ... },
    "issuanceDate": "2024-01-01T00:00:00Z",
    "proof": { ... }
  }
}

POST /vc/issue/batch

Batch issue multiple verifiable credentials.

Authentication: Required (JWT, roles: admin, issuer)

Request Body:

{
  "credentials": [
    {
      "subject": "did:web:subject1.com",
      "credentialSubject": { "name": "User 1" }
    },
    {
      "subject": "did:web:subject2.com",
      "credentialSubject": { "name": "User 2" }
    }
  ]
}

Response (200):

{
  "jobId": "batch-job-id",
  "total": 2,
  "accepted": 2,
  "results": [
    {
      "index": 0,
      "credentialId": "credential-id-1"
    },
    {
      "index": 1,
      "credentialId": "credential-id-2"
    }
  ]
}

POST /vc/verify

Verify a verifiable credential.

Authentication: Required (JWT)

Request Body:

{
  "credential": {
    "id": "credential-id",
    "proof": { ... }
  }
}

Response (200):

{
  "verified": true,
  "credentialId": "credential-id",
  "verifiedAt": "2024-01-01T00:00:00Z"
}

---

Microsoft Entra VerifiedID

POST /vc/issue/entra

Issue credential via Microsoft Entra VerifiedID.

Request Body:

{
  "claims": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "pin": "optional-pin",
  "callbackUrl": "https://example.com/callback"
}

Response (200):

{
  "requestId": "entra-request-id",
  "url": "https://verifiedid.did.msidentity.com/...",
  "qrCode": "data:image/png;base64,..."
}

POST /vc/verify/entra

Verify credential via Microsoft Entra VerifiedID.

Request Body:

{
  "credential": { ... }
}

Response (200):

{
  "verified": true
}

POST /eidas/verify-and-issue

Verify eIDAS signature and issue credential via Entra VerifiedID.

Request Body:

{
  "document": "base64-encoded-document",
  "userId": "user-id",
  "userEmail": "user@example.com",
  "pin": "optional-pin"
}

Response (200):

{
  "verified": true,
  "credentialRequest": {
    "requestId": "request-id",
    "url": "https://...",
    "qrCode": "data:image/png;base64,..."
  }
}

---

Credential Templates

POST /templates

Create a credential template.

Authentication: Required (JWT, roles: admin, issuer)

Request Body:

{
  "name": "user-registration",
  "description": "Template for user registration credentials",
  "credential_type": ["VerifiableCredential", "IdentityCredential"],
  "template_data": {
    "name": "{{name}}",
    "email": "{{email}}",
    "registeredAt": "{{registeredAt}}"
  },
  "version": 1,
  "is_active": true
}

GET /templates

List credential templates.

Authentication: Required (JWT)

Query Parameters:

• activeOnly (boolean): Filter to active templates only
• limit (number): Maximum number of results
• offset (number): Pagination offset

GET /templates/:id

Get credential template by ID.

Authentication: Required (JWT)

GET /templates/name/:name

Get credential template by name.

Authentication: Required (JWT)

Query Parameters:

• version (number, optional): Specific version, or latest active if omitted

PATCH /templates/:id

Update credential template.

Authentication: Required (JWT, roles: admin, issuer)

POST /templates/:id/version

Create new template version.

Authentication: Required (JWT, roles: admin, issuer)

POST /templates/:id/render

Render template with variables.

Authentication: Required (JWT)

Request Body:

{
  "variables": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

---

Judicial Credentials

POST /judicial/issue

Issue judicial credential.

Authentication: Required (JWT, roles: admin, judicial-admin)

Request Body:

{
  "subjectDid": "did:web:judge.com",
  "role": "Judge",
  "appointmentDate": "2024-01-01T00:00:00Z",
  "appointmentAuthority": "The Order",
  "jurisdiction": "International",
  "termLength": 4,
  "expirationDate": "2028-01-01T00:00:00Z"
}

Available Roles:

• Registrar
• JudicialAuditor
• ProvostMarshal
• Judge
• CourtClerk
• Bailiff
• CourtOfficer

GET /judicial/template/:role

Get judicial credential template for role.

Authentication: Required (JWT)

---

Financial Credentials

POST /financial-credentials/issue

Issue financial role credential.

Authentication: Required (JWT, roles: admin, financial-admin)

Request Body:

{
  "subjectDid": "did:web:financial-officer.com",
  "role": "ComptrollerGeneral",
  "appointmentDate": "2024-01-01T00:00:00Z",
  "appointmentAuthority": "The Order",
  "jurisdiction": "International",
  "termLength": 4
}

Available Roles:

• ComptrollerGeneral
• MonetaryComplianceOfficer
• CustodianOfDigitalAssets
• FinancialAuditor
• Treasurer
• ChiefFinancialOfficer

GET /financial-credentials/template/:role

Get financial credential template for role.

Authentication: Required (JWT)

---

Diplomatic Credentials

POST /diplomatic/letters-of-credence/issue

Issue Letters of Credence.

Authentication: Required (JWT, roles: admin, diplomatic-admin)

Request Body:

{
  "recipientDid": "did:web:ambassador.com",
  "recipientName": "John Doe",
  "recipientTitle": "Ambassador",
  "missionCountry": "United States",
  "missionType": "embassy",
  "appointmentDate": "2024-01-01T00:00:00Z",
  "expirationDate": "2028-01-01T00:00:00Z",
  "useEntraVerifiedID": true
}

Mission Types:

• embassy
• consulate
• delegation
• mission

GET /diplomatic/letters-of-credence/:credentialId/status

Get Letters of Credence status.

Authentication: Required (JWT)

POST /diplomatic/letters-of-credence/:credentialId/revoke

Revoke Letters of Credence.

Authentication: Required (JWT, roles: admin, diplomatic-admin)

Request Body:

{
  "reason": "End of term"
}

---

Metrics and Audit

GET /metrics

Get credential issuance metrics.

Authentication: Required (JWT, roles: admin, monitor)

Query Parameters:

• startDate (ISO 8601): Start date for metrics
• endDate (ISO 8601): End date for metrics

Response:

{
  "issuedToday": 10,
  "issuedThisWeek": 50,
  "issuedThisMonth": 200,
  "issuedThisYear": 2000,
  "successRate": 99.5,
  "failureRate": 0.5,
  "totalIssuances": 2000,
  "totalFailures": 10,
  "averageIssuanceTime": 500,
  "p50IssuanceTime": 400,
  "p95IssuanceTime": 1000,
  "p99IssuanceTime": 2000,
  "byCredentialType": {
    "VerifiableCredential,IdentityCredential": 1000,
    "VerifiableCredential,JudicialCredential": 500
  },
  "byAction": {
    "issued": 2000,
    "revoked": 50
  },
  "recentIssuances": [ ... ]
}

GET /metrics/dashboard

Get metrics dashboard data.

Authentication: Required (JWT, roles: admin, monitor)

POST /metrics/audit/search

Search audit logs.

Authentication: Required (JWT, roles: admin, auditor)

Request Body:

{
  "credentialId": "credential-id",
  "issuerDid": "did:web:issuer.com",
  "subjectDid": "did:web:subject.com",
  "credentialType": ["VerifiableCredential"],
  "action": "issued",
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-12-31T23:59:59Z",
  "page": 1,
  "pageSize": 50
}

POST /metrics/audit/export

Export audit logs.

Authentication: Required (JWT, roles: admin, auditor)

Request Body:

{
  "credentialId": "credential-id",
  "startDate": "2024-01-01T00:00:00Z",
  "endDate": "2024-12-31T23:59:59Z",
  "format": "json"
}

Formats: json, csv

---

Azure Logic Apps Workflows

POST /workflow/eidas-verify-and-issue

Trigger eIDAS verification and issuance workflow via Logic Apps.

Request Body:

{
  "eidasSignature": { ... },
  "subject": "did:web:subject.com",
  "credentialSubject": { ... }
}

POST /workflow/appointment-credential

Trigger appointment credential issuance workflow.

Request Body:

{
  "userId": "user-id",
  "role": "Judge",
  "appointmentDate": "2024-01-01T00:00:00Z",
  "termEndDate": "2028-01-01T00:00:00Z"
}

POST /workflow/batch-renewal

Trigger batch renewal workflow.

Request Body:

{
  "credentialIds": ["credential-id-1", "credential-id-2"]
}

POST /workflow/document-attestation

Trigger document attestation workflow.

Request Body:

{
  "documentId": "document-id",
  "attestorDid": "did:web:attestor.com"
}

---

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body"
  }
}

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

403 Forbidden

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}

404 Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}

500 Internal Server Error

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

---

Rate Limiting

Credential issuance endpoints are rate-limited to prevent abuse:

• Default: 100 requests per hour per IP
• Authenticated users: 500 requests per hour per user
• Admin users: 1000 requests per hour per user

Rate limit headers are included in responses:

• X-RateLimit-Limit: Maximum requests allowed
• X-RateLimit-Remaining: Remaining requests in current window
• X-RateLimit-Reset: Time when the rate limit resets

---

Swagger UI

Interactive API documentation is available at:

• Development: http://localhost:4002/docs
• Production: https://api.theorder.org/identity/docs

---

Environment Variables

Variable	Description	Default
PORT	Server port	4002
NODE_ENV	Environment	development
DATABASE_URL	PostgreSQL connection string	-
KMS_KEY_ID	AWS KMS key ID	-
KMS_REGION	AWS region	us-east-1
VC_ISSUER_DID	Verifiable credential issuer DID	-
VC_ISSUER_DOMAIN	Issuer domain (alternative to DID)	-
ENTRA_TENANT_ID	Microsoft Entra tenant ID	-
ENTRA_CLIENT_ID	Microsoft Entra client ID	-
ENTRA_CLIENT_SECRET	Microsoft Entra client secret	-
EIDAS_PROVIDER_URL	eIDAS provider URL	-
EIDAS_API_KEY	eIDAS API key	-
REDIS_URL	Redis connection URL	-
SWAGGER_SERVER_URL	Swagger server URL	-

---

Examples

Issue a Credential

curl -X POST http://localhost:4002/vc/issue \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "did:web:subject.com",
    "credentialSubject": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'

Verify a Credential

curl -X POST http://localhost:4002/vc/verify \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "credential": {
      "id": "credential-id",
      "proof": { ... }
    }
  }'

Get Metrics

curl -X GET "http://localhost:4002/metrics?startDate=2024-01-01T00:00:00Z&endDate=2024-12-31T23:59:59Z" \
  -H "Authorization: Bearer <token>"