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**:
```json
{
  "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**:
```json
{
  "subject": "did:web:subject.com",
  "credentialSubject": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "expirationDate": "2025-12-31T23:59:59Z"
}
```

**Response** (200):
```json
{
  "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**:
```json
{
  "credentials": [
    {
      "subject": "did:web:subject1.com",
      "credentialSubject": { "name": "User 1" }
    },
    {
      "subject": "did:web:subject2.com",
      "credentialSubject": { "name": "User 2" }
    }
  ]
}
```

**Response** (200):
```json
{
  "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**:
```json
{
  "credential": {
    "id": "credential-id",
    "proof": { ... }
  }
}
```

**Response** (200):
```json
{
  "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**:
```json
{
  "claims": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "pin": "optional-pin",
  "callbackUrl": "https://example.com/callback"
}
```

**Response** (200):
```json
{
  "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**:
```json
{
  "credential": { ... }
}
```

**Response** (200):
```json
{
  "verified": true
}
```

#### `POST /eidas/verify-and-issue`

Verify eIDAS signature and issue credential via Entra VerifiedID.

**Request Body**:
```json
{
  "document": "base64-encoded-document",
  "userId": "user-id",
  "userEmail": "user@example.com",
  "pin": "optional-pin"
}
```

**Response** (200):
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "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**:
```json
{
  "eidasSignature": { ... },
  "subject": "did:web:subject.com",
  "credentialSubject": { ... }
}
```

#### `POST /workflow/appointment-credential`

Trigger appointment credential issuance workflow.

**Request Body**:
```json
{
  "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**:
```json
{
  "credentialIds": ["credential-id-1", "credential-id-2"]
}
```

#### `POST /workflow/document-attestation`

Trigger document attestation workflow.

**Request Body**:
```json
{
  "documentId": "document-id",
  "attestorDid": "did:web:attestor.com"
}
```

---

## Error Responses

All endpoints may return the following error responses:

### 400 Bad Request
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body"
  }
}
```

### 401 Unauthorized
```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}
```

### 403 Forbidden
```json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}
```

### 404 Not Found
```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found"
  }
}
```

### 500 Internal Server Error
```json
{
  "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

```bash
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

```bash
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

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