API reference¶
Every HTTP surface of the backend in one place. Business endpoints are prefixed
/api/v1/*; the OIDC provider and infrastructure endpoints sit at the root.
The browser never calls these directly
The frontend is a BFF: the browser only talks to same-origin /api/*
Next.js routes, which proxy to the backend server-side. Tokens never reach
client JS. The paths below are the backend paths.
Swagger: GET /swagger/doc.json (bearer token required in production).
Infrastructure¶
| Method | Path | Access |
|---|---|---|
GET |
/health |
public |
GET |
/ready |
public |
GET |
/metrics |
OBSERVABILITY_TOKEN in production (otherwise 404) |
GET |
/swagger/doc.json |
same |
OIDC provider¶
Enabled once OAUTH_ISSUER + SSO_STATE_KEY are set. The paths are fixed by
the OIDC specification.
| Method | Path |
|---|---|
GET |
/.well-known/openid-configuration |
GET |
/.well-known/jwks.json |
GET |
/oauth2/auth |
POST |
/oauth2/token |
POST |
/oauth2/introspect |
POST |
/oauth2/revoke |
GET |
/oauth2/sessions/logout |
GET POST |
/userinfo |
Internal login/consent API: /api/v1/provider/login · /consent ·
/login/accept · /login/reject · /consent/accept · /consent/reject ·
/logout/accept.
Authentication — /api/v1/auth¶
| Method | Path | Limit |
|---|---|---|
POST |
/eid/start |
auth (5/min) |
POST |
/eid/start-id |
auth |
POST |
/eid/poll |
poll (1/sec, burst 30) |
POST |
/google |
auth |
DELETE |
/google/link |
signed in |
POST |
/refresh · /logout |
auth |
POST |
/initiate |
auth (mobile) |
GET |
/status/{sid} |
poll (mobile) |
Super admin: /api/v1/auth/superadmin/mfa ·
/onboard/{google,eid/start,eid/start-id,eid/poll,email/send,email/verify,totp/init,totp/verify}.
Gerege SSO (RP side): /api/v1/sso/start · /callback · /native · /logout.
Users and organisations¶
| Method | Path | What |
|---|---|---|
GET |
/api/v1/users/me |
Own profile |
GET |
/api/v1/users/me/eid/summary · /certificates · /devices · /activity |
eID PKI profile |
GET POST DELETE |
/api/v1/users/me/eid/organizations… |
Linked organisations |
GET POST DELETE |
/api/v1/users/me/eid/organizations/{regNo}/signers… |
Authorised signers |
POST GET |
/api/v1/org |
Create / my organisations |
GET |
/api/v1/org/lookup/{regNo} |
Look up in the state register |
GET POST PUT DELETE |
/api/v1/org/{id}/members… |
Members and roles |
GET |
/api/v1/core/users · /organizations |
Admin search (users.manage) |
eID Service Proxy¶
| Method | Path | Grant |
|---|---|---|
GET |
/api/v1/eid/summary · /certificates · /devices · /activity |
svc:eid-proxy |
GET |
/api/v1/eid-org/organizations · /organizations/{regNo}/signers |
svc:eid-org-proxy |
* |
/rp/sign/* |
svc:eid-sign |
Citizen services — /api/v1/gov¶
Listed in full on Citizen services.
Public catalogue: /api/v1/catalog/services · /services/{id} · /life-events.
Registry and Relay¶
Listed in full on Registry & Relay
(/api/v1/registry/*, /api/v1/relay/*).
Gateway and app registry¶
| Method | Path | Permission |
|---|---|---|
GET |
/api/v1/gateway/overview · /logs |
gateway.manage |
GET POST PUT DELETE |
/api/v1/gateway/services… |
gateway.manage |
GET POST |
/api/v1/applications |
gateway.manage |
GET PUT DELETE |
/api/v1/applications/{id} |
gateway.manage |
POST |
/api/v1/applications/{id}/rotate-secret |
gateway.manage |
PUT |
/api/v1/applications/{id}/secret · /services |
gateway.manage |
Signing, assets, files¶
| Method | Path |
|---|---|
POST |
/api/v1/sign/initiate · /init |
GET |
/api/v1/sign/status/{sid} · /{id} · /{id}/download |
GET PUT DELETE |
/api/v1/me/signature |
PUT |
/api/v1/me/latin-name · /org-name-latin/{regNo} |
GET PUT DELETE |
/api/v1/me/orgstamp/{regNo} |
GET POST DELETE |
/api/v1/gspace · /upload · /download |
GET POST DELETE |
/api/v1/integrations… |
Details: Documents, signing, files.
AI¶
| Method | Path | Limit |
|---|---|---|
POST |
/api/v1/ai/chat · /stt · /tts · /translate |
20/min, burst 10 |
POST |
/api/v1/public/ai/chat · /chat/stream |
6/min, burst 3 |
POST |
/api/v1/public/ai/tts |
20/min, burst 8 |
Details: AI pipeline.
Admin, RBAC, audit¶
| Method | Path | Permission |
|---|---|---|
GET |
/api/v1/rbac/me |
signed in |
GET POST PUT DELETE |
/api/v1/rbac/roles… · /permissions |
roles.manage |
GET POST PUT DELETE |
/api/v1/admin/users… |
users.manage |
GET PUT |
/api/v1/admin/ai/prompts… |
settings.manage |
POST |
/api/v1/admin/ai/knowledge/reindex |
settings.manage |
GET POST PUT DELETE |
/api/v1/superadmin/… |
superadmin |
GET |
/api/v1/audit · /audit/verify |
admin |
POST |
/api/v1/security/events |
signed in |
GET |
/api/v1/security/events |
admin |
GET PUT |
/api/v1/site/appearance |
public / settings.manage |
GET POST PUT DELETE |
/api/v1/themes… |
public (/active) / admin |
Details: Admin, RBAC, audit.
Error model¶
Handlers have the shape func(w, r) error and are wrapped by v1.Wrap. The
usecase layer returns apperror.*, which is mapped to an HTTP status in one
place. Internal causes are wrapped with apperror.InternalCause, so library
errors never leak to clients.