API reference

Every REST endpoint on one page. Base path: /api/v1 (except the OIDC and relay surfaces). Swagger UI: /swagger/ — gated by OBSERVABILITY_TOKEN in production.

Response shape

{ "status": true, "message": "success", "data": { … } }

Errors:

{ "status": false, "message": "…", "error": "…" }

Usecases return apperror.*, mapped to HTTP statuses. Internal causes never reach clients.

Authentication — /v1/auth

Method	Path	Access	What
POST	/eid/start	public	QR + deep-link session
POST	/eid/start-id	public	Push by national ID
POST	/eid/poll	public	Long poll (~60/min)
GET	/status/{sid}	public	Session state
POST	/google	public	Google code exchange
DELETE	/google/link	authenticated	Unlink Google
POST	/refresh	public	Rotate tokens
POST	/logout	authenticated	End the session
POST	/initiate	public	Start a flow

Rate limit ~5/min, body cap 4 KiB.

Super-admin onboarding — /v1/auth/superadmin

Method	Path	What
POST	/mfa	Verify MFA
POST	/onboard/google	Google verification
POST	/onboard/eid/start · /start-id · /poll	eID verification
POST	/onboard/email/send · /verify	E-mail OTP
POST	/onboard/totp/init · /verify	TOTP and recovery codes

Users and profile

Method	Path	Access	What
GET	/v1/users/me	authenticated	My profile
GET	/v1/rbac/me	authenticated	My role and permissions

Assets — /v1/me

Method	Path	What
GET · PUT · DELETE	/signature	Signature image
PUT	/latin-name	Latin name
GET · PUT · DELETE	/orgstamp/{regNo}	Organisation stamp
PUT	/org-name-latin/{regNo}	Organisation Latin name

eID profile — /v1/users/me/eid

Method	Path	What
GET	/summary · /certificates · /devices · /activity	PKI console
GET · POST	/organizations	Linked organisations
DELETE	/organizations/{regNo}	Unlink
GET · POST · DELETE	/organizations/{regNo}/signers	Authorised signers
POST	/organizations/{regNo}/signers/resend	Resend the invite

RBAC — /v1/rbac

Method	Path	Permission
GET	/roles · /permissions	roles.manage
POST	/roles	roles.manage
PUT	/roles/{id} · /roles/{id}/permissions	roles.manage
DELETE	/roles/{id}	roles.manage

Organisations — /v1/org

Method	Path	What
GET · POST	/	List / create
GET	/lookup/{regNo}	State-registry lookup
GET	/{id}	Details
GET · POST	/{id}/members	Members
PUT · DELETE	/{id}/members/{userID}	Role / removal

Government services — /v1/gov

Method	Path	Access	What
GET	/services · /life-events · /overview	authenticated	Catalogue, overview
GET · POST	/applications	authenticated	My applications
GET	/applications/{id}/timeline	authenticated	History
POST	/applications/{id}/provide-info · /cancel	authenticated	Evidence / withdraw
GET · POST	/references	authenticated	Certificates
GET	/notifications	authenticated	Notifications
POST	/notifications/{id}/read · /read-all	authenticated	Mark read
GET	/payments	authenticated	Payments
POST	/payments/{id}/pay	authenticated	Pay
GET · POST	/appointments	authenticated	Appointments
POST	/appointments/{id}/cancel	authenticated	Cancel

Officer — /v1/gov/officer

Method	Path	Permission
GET	/stats · /queue · /queue/{id}	gov.review
POST	/queue/{id}/assign · /decide · /complete · /request-info	gov.review

Catalogue — /v1/catalog

Method	Path	What
GET	/services · /services/{id}	Published services
GET	/life-events	Life events

Registry — /v1/registry

Method	Path	Permission
GET	/overview · /catalog · /once-only	registry.view
GET	/services · /services/{id} · /{id}/versions · /{id}/once-only	registry.view
GET	/evidences · /life-events	registry.view
POST · PUT · DELETE	/services[/{id}]	registry.manage
POST	/services/{id}/publish · /archive	registry.manage
PUT	/services/{id}/evidences	registry.manage
POST · PUT · DELETE	/evidences[/{id}]	registry.manage
POST · DELETE	/life-events[/{id}]	registry.manage

Relay — /v1/relay

Method	Path	Permission
GET	/overview · /requests · /requests/{id}	relay.view
POST	/requests · /requests/{id}/forward	relay.manage
POST	/assignments/{id}/respond	relay.manage
GET · POST · DELETE	/platforms[/{id}]	relay.manage
GET · POST · DELETE	/routes[/{id}]	relay.manage
POST	/v1/relay/webhook	webhook signature

API Gateway — /v1/gateway

Method	Path	Permission
GET	/overview · /logs	gateway.manage
GET · POST	/services	gateway.manage
PUT · DELETE	/services/{id}	gateway.manage

Applications — /v1/applications

Method	Path	Permission
GET · POST	/	gateway.manage
GET · PUT · DELETE	/{id}	gateway.manage
POST	/{id}/rotate-secret	gateway.manage
PUT	/{id}/secret · /{id}/services	gateway.manage

eID proxy — /v1/eid, /v1/eid-org

Method	Path	Check
GET	/v1/eid/summary · /certificates · /devices · /activity	svc:eid-proxy scope
GET	/v1/eid-org/organizations · /organizations/{regNo}/signers	svc:eid-org-proxy scope

Signing — /v1/sign

Method	Path	What
POST	/init	Session from a PDF
POST	/initiate	Session from a digest
GET	/status/{sid}	State
GET	/{id} · /{id}/download	Details / download

Integrations and storage

Method	Path	What
GET · POST	/v1/integrations	Connections
GET	/v1/integrations/{provider}/token	Token
DELETE	/v1/integrations/{provider}	Disconnect
GET	/v1/gspace/ · /download	List / download
POST	/v1/gspace/upload	Upload
DELETE	/v1/gspace/	Delete

AI — /v1/ai, /v1/public/ai

Method	Path	Access
POST	/v1/ai/chat · /stt · /tts · /translate	authenticated (~20/min)
POST	/v1/public/ai/chat · /chat/stream · /tts	public (~6/min)

Admin — /v1/admin

Method	Path	Permission
GET · POST	/users	users.manage
PUT	/users/{id}/role · /users/{id}/active	users.manage
DELETE	/users/{id}	users.manage
GET	/ai/prompts	settings.manage
PUT	/ai/prompts/{key}	settings.manage
POST	/ai/knowledge/reindex	settings.manage

Super admin — /v1/superadmin

Method	Path
GET · POST	/admins · /admins/by-register
PUT	/admins/{id}/grant
DELETE	/admins/{id}
GET · POST	/invites
DELETE	/invites/{email}
GET · PUT	/access-mode

Audit, security, appearance

Method	Path	Permission
GET	/v1/audit/ · /verify	admin
GET	/v1/security/events	admin
POST	/v1/security/events	authenticated
GET	/v1/site/appearance	public
PUT	/v1/site/appearance	settings.manage
GET	/v1/themes/active · / · /{id}	public / authenticated
POST · PUT · DELETE	/v1/themes[/{id}]	settings.manage
PUT	/v1/themes/{id}/active	settings.manage
GET	/v1/core/users · /organizations	admin

SSO client — /v1/sso

Method	Path	What
POST	/start · /callback	Authorize → tokens
POST	/native	Mobile PKCE
POST	/logout	RP-initiated logout

OIDC provider (at the root)

Method	Path
GET	/.well-known/openid-configuration · /.well-known/jwks.json
GET	/oauth2/auth · /oauth2/sessions/logout
POST	/oauth2/token · /oauth2/introspect · /oauth2/revoke
GET · POST	/userinfo

Provider challenges — /v1/provider

Method	Path
GET	/login · /consent
POST	/login/accept · /login/reject
POST	/consent/accept · /consent/reject
POST	/logout/accept

Operator and relay surfaces

Path	Authentication
/admin/api/v1/*	Admin API key (gsk_…) — loopback
/rp/sign/*	SIGN_RELAY_TOKEN

Ops

Path	What	Production
/health	Liveness	public
/metrics	Prometheus	bearer token
/swagger/*	Swagger UI + JSON	bearer token