Passport API Reference

All Passport endpoints are served under the /api/v1/passport prefix via the gateway.

Endpoints

Method	Path	Description
GET	/api/v1/passport/providers	List OAuth providers
POST	/api/v1/passport/providers	Register provider
POST	/api/v1/passport/authorizations	Create authorization
GET	/api/v1/passport/audit	View audit trail

Examples

Register an OAuth Provider

curl -X POST http://localhost:3000/api/v1/passport/providers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github",
    "type": "oauth2",
    "clientId": "Iv1.abc123def456",
    "scopes": ["repo", "user", "read:org"],
    "redirectUri": "https://app.example.com/auth/callback"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "p1q2r3s4",
    "name": "github",
    "type": "oauth2",
    "clientId": "Iv1.abc123def456",
    "scopes": ["repo", "user", "read:org"],
    "redirectUri": "https://app.example.com/auth/callback",
    "createdAt": "2026-03-05T12:00:00.000Z"
  }
}

List All Providers

curl http://localhost:3000/api/v1/passport/providers

Response:

{
  "success": true,
  "data": [
    {
      "id": "p1q2r3s4",
      "name": "github",
      "type": "oauth2",
      "clientId": "Iv1.abc123def456",
      "scopes": ["repo", "user", "read:org"],
      "redirectUri": "https://app.example.com/auth/callback",
      "createdAt": "2026-03-05T12:00:00.000Z"
    }
  ]
}

Create an Authorization

curl -X POST http://localhost:3000/api/v1/passport/authorizations \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "p1q2r3s4",
    "userId": "user-abc",
    "scopes": ["repo", "user"],
    "token": "gho_xxxxxxxxxxxx",
    "expiresAt": "2026-06-05T12:00:00.000Z"
  }'

Response:

{
  "success": true,
  "data": {
    "id": "t5u6v7w8",
    "providerId": "p1q2r3s4",
    "userId": "user-abc",
    "scopes": ["repo", "user"],
    "token": "gho_xxxxxxxxxxxx",
    "expiresAt": "2026-06-05T12:00:00.000Z",
    "createdAt": "2026-03-05T12:00:00.000Z"
  }
}

View Audit Trail

curl http://localhost:3000/api/v1/passport/audit

Response:

{
  "success": true,
  "data": [
    {
      "id": "a1b2c3d4",
      "action": "authorization.created",
      "providerId": "p1q2r3s4",
      "userId": "user-abc",
      "timestamp": "2026-03-05T12:00:00.000Z"
    }
  ]
}

Response Envelope

All responses follow the standard envelope format:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Provider not found"
  }
}