Admin API

The Admin API powers the IDToken Console — the web-based administration dashboard for managing enrollments, reviewing sessions, querying audit logs, and monitoring trust infrastructure.

All admin endpoints require a JWT with idtoken:admin or idtoken:audit scope. Super admins (role: "super_admin") have access to all endpoints.

Rate limit: 60 requests per minute.

Enrollment Management

List Enrollments

GET /admin/enrollments

List all enrollments with pagination and filtering.

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Results per page
`token_id`	string	—	Filter by token ID (partial match)
`trust_level`	number	—	Filter by trust level (1, 2, 3)
`is_revoked`	boolean	—	Filter by revocation status

Response (200 OK)

{
  "enrollments": [
    {
      "id": "uuid",
      "token_id": "vds-uuid-12345",
      "device_id": "device-uuid",
      "trust_level": 3,
      "is_revoked": false,
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-10T08:00:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 20
}

Get Enrollment Details

GET /admin/enrollments/:tokenId

Get detailed enrollment information including recent authentication sessions.

Response (200 OK)

{
  "enrollment": {
    "id": "uuid",
    "token_id": "vds-uuid-12345",
    "device_id": "device-uuid",
    "trust_level": 3,
    "is_revoked": false,
    "created_at": "2025-01-10T08:00:00Z"
  },
  "recentSessions": [
    {
      "session_id": "sess_abc123",
      "status": "approved",
      "initiated_at": "2025-01-15T10:00:00Z",
      "resolved_at": "2025-01-15T10:00:45Z",
      "service_id": "my-web-app"
    }
  ]
}

Session Management

List Sessions

GET /admin/sessions

List authentication sessions (from PostgreSQL audit records).

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	20	Results per page
`token_id`	string	—	Filter by token ID
`status`	string	—	Filter: `pending`, `approved`, `rejected`, `expired`

Get Session Details

GET /admin/sessions/:sessionId

Get detailed session information.

List Active Sessions

GET /admin/sessions/live

Get currently active sessions from Redis (sessions awaiting user confirmation).

Response (200 OK)

{
  "sessions": [
    {
      "sessionId": "sess_abc123",
      "tokenId": "vds-uuid-12345",
      "status": "pending",
      "expiresAt": "2025-01-15T10:01:00Z",
      "serviceId": "my-web-app"
    }
  ],
  "count": 3
}

Audit Log

Query Audit Log

GET /admin/audit

Query the immutable audit log with filtering and pagination.

Query Parameters

Parameter	Type	Default	Description
`page`	number	1	Page number
`limit`	number	50	Results per page
`event_type`	string	—	Filter by event type
`token_id`	string	—	Filter by token ID
`session_id`	string	—	Filter by session ID

Event Types

Event	Description
`ENROLL`	Successful enrollment
`AUTH_INITIATE`	Auth session started
`AUTH_APPROVE`	Auth approved by user
`AUTH_REJECT`	Auth rejected (invalid OTP/signature)
`AUTH_EXPIRE`	Auth session expired
`REVOKE`	Enrollment revoked
`VDS_VERIFY_OK`	VDS verification succeeded
`VDS_VERIFY_FAIL`	VDS verification failed
`VDS_REVOKED`	VDS found on revocation list
`VDS_TEST_CERT`	VDS signed with test certificate
`SAML_SSO_SUCCESS`	SAML SSO completed successfully
`SAML_SSO_FAIL`	SAML SSO failed
`SAML_SLO`	SAML Single Logout processed
`CONSENT_GRANTED`	User granted all requested scopes
`CONSENT_PARTIAL`	User granted partial scopes
`CONSENT_DENIED`	User denied all scopes
`ADMIN_REVOKE`	Admin-initiated revocation
`ADMIN_OPERATOR_CREATE`	Admin operator created
`ADMIN_OPERATOR_DELETE`	Admin operator deleted
`ADMIN_TRUST_REFRESH`	Trust lists refreshed

Response (200 OK)

{
  "events": [
    {
      "id": 1234,
      "event_type": "AUTH_APPROVE",
      "token_id": "vds-uuid-12345",
      "session_id": "sess_abc123",
      "details": { "service_id": "my-web-app", "scopes": ["identity:name"] },
      "client_ip": "203.0.113.42",
      "occurred_at": "2025-01-15T10:00:45Z"
    }
  ],
  "total": 5678,
  "page": 1,
  "limit": 50
}

Trust Infrastructure

Get Trust Status

GET /admin/trust/status

Get the current status of VDS trust list caches.

Response (200 OK)

{
  "governance": {
    "status": "cached",
    "lastRefreshed": "2025-01-15T09:00:00Z",
    "expiresAt": "2025-01-15T10:00:00Z"
  },
  "schemeLists": [
    {
      "iac": "VDS",
      "status": "cached",
      "lastRefreshed": "2025-01-15T09:00:00Z"
    }
  ]
}

Refresh Trust Lists

POST /admin/trust/refresh

Force-refresh all VDS trust lists from upstream sources. Requires idtoken:admin scope.

Response (200 OK)

{
  "refreshed": true,
  "governance": "ok",
  "schemeLists": 1,
  "trustServiceLists": 3,
  "certificates": 12
}

Statistics

Get Server Statistics

GET /admin/stats

Get 24-hour server statistics.

Response (200 OK)

{
  "period": "24h",
  "enrollments": {
    "total": 142,
    "new": 5,
    "revoked": 1
  },
  "sessions": {
    "total": 387,
    "approved": 352,
    "rejected": 28,
    "expired": 7
  }
}

Admin Operators

Admin operators authenticate using IDToken itself — they enroll with their own VDS credential and are assigned admin roles.

Role	Permissions
`operator`	View enrollments, sessions, audit log
`auditor`	Read-only access to audit log
`super_admin`	Full access: revoke, manage operators, refresh trust