API Reference
Self-hosted application programming interface (API) routes and their authentication models.
All SURADAR API surfaces are self-hosted. Glyphzero does not run a hosted API. The base URL is wherever the customer runs the service.
suradar-pdp
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /v1/authorize | Tool authorization decision | Monitor bearer token configured in the service, plus a verified delegation chain |
| GET | /healthz | Liveness | None |
| GET | /readyz | Readiness | None |
| GET | /metrics | Metrics | None |
| POST | /v1/fga/check | Relationship check, only when the fga config section is enabled | Monitor bearer token |
Management API
These routes are available only when management is enabled in config. Each bearer credential is bound to one organization, with role-based grants.
| Method | Path | Purpose | Auth |
|---|---|---|---|
| POST | /api/v1/zones/{zone}/{kind} | Create an object | Organization-bound bearer credential with role-based grants |
| GET | /api/v1/zones/{zone}/{kind} | List objects | Organization-bound bearer credential with role-based grants |
| GET | /api/v1/objects/{id} | Read an object | Organization-bound bearer credential with role-based grants |
| PATCH | /api/v1/objects/{id} | Update an object | Organization-bound bearer credential with role-based grants |
| DELETE | /api/v1/objects/{id} | Delete an object | Organization-bound bearer credential with role-based grants |
Optional server section
The optional server section serves audit and approval routes under /api/v1/ over the decisions the binary recorded.
Go library server routes
An integrator mounts these routes by embedding suradar/server.
Admin API
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /api/v1/admin/agents | List agents | Admin API key, bearer |
| POST | /api/v1/admin/agents | Create an agent | Admin API key, bearer |
| GET | /api/v1/admin/agents/{id} | Read an agent | Admin API key, bearer |
| PATCH | /api/v1/admin/agents/{id} | Update an agent | Admin API key, bearer |
| DELETE | /api/v1/admin/agents/{id} | Delete an agent | Admin API key, bearer |
| POST | /api/v1/admin/agents/{id}/suspend | Suspend an agent | Admin API key, bearer |
| POST | /api/v1/admin/agents/{id}/reactivate | Reactivate an agent | Admin API key, bearer |
| GET | /api/v1/admin/policies | List policies | Admin API key, bearer |
| GET | /api/v1/admin/policies/{id}/versions | List policy versions | Admin API key, bearer |
| POST | /api/v1/admin/policies/{id}/versions | Create a policy version | Admin API key, bearer |
| POST | /api/v1/admin/policies/{id}/versions/{vid}/activate | Activate a policy version | Admin API key, bearer |
| POST | /api/v1/admin/policies/{id}/versions/{vid}/archive | Archive a policy version | Admin API key, bearer |
| GET | /api/v1/admin/audit | Query audit records | Admin API key, bearer |
| GET | /api/v1/admin/audit/stats | Audit statistics | Admin API key, bearer |
| GET | /api/v1/admin/usage | Usage | Admin API key, bearer |
| GET | /api/v1/admin/usage/history | Usage history | Admin API key, bearer |
| GET | /api/v1/admin/health | Health | Admin API key, bearer |
Approvals
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /api/v1/approvals/pending | List pending approvals | Admin key or tenant key |
| POST | /api/v1/approvals/{id}/decide | Decide an approval | Admin key or tenant key |
Tenant routes
Evidence routes need the transparency layer enabled.
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /api/v1/audit/events | Tenant audit events | Tenant key |
| GET | /api/v1/evidence/checkpoint | Evidence checkpoint | Tenant key, or admin key when tenant auth is not configured |
| GET | /api/v1/evidence/bundle | Export a verifiable evidence bundle | Tenant key, or admin key when tenant auth is not configured |
| POST | /api/v1/evidence/bundle | Export a verifiable evidence bundle | Tenant key, or admin key when tenant auth is not configured |
| GET | /api/v1/rights/explanations/{logID}/{index} | Read an explanation | Tenant key |
| POST | /api/v1/rights/contests | Submit a contest | Tenant key |
| GET | /api/v1/rights/subjects/{subject}/export | Export subject data | Tenant key |
Agent routes
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /api/v1/usage | Usage | Signed agent requests through the L1 to L5 stack |
Unauthenticated routes
| Method | Path | Purpose | Auth |
|---|---|---|---|
| GET | /healthz | Health | None |
| POST | /register | Dynamic client registration, when configured | None |
| GET | /register/{id} | Read dynamic client registration, when configured | None |
Errors
Admin API errors return a JavaScript Object Notation (JSON) object containing an error object with code and message fields.
Request signing and attestation formats are not published here.