eID Service Proxy

A citizen's eID PKI profile — linked organisations, certificates, registered devices and activity history — is reachable two ways:

1. For the platform's own users (/v1/users/me/eid/*) — Gerege App fetches it with its own eID RP credentials or through the SSO proxy.
2. For registered apps (/v1/eid/*, /v1/eid-org/*) — Gerege App acts as a proxy and exposes the data to RPs.

1. The user's own eID console

UI: /me/eid/{id, certificates, devices, logs, security, sign}.

Endpoint	What
GET /v1/users/me/eid/summary	Console totals
GET /v1/users/me/eid/certificates	Certificates and status
GET /v1/users/me/eid/devices	Registered devices
GET /v1/users/me/eid/activity	Authentication / signing history
GET/POST /v1/users/me/eid/organizations	Linked organisations
DELETE /v1/users/me/eid/organizations/{regNo}	Unlink
GET/POST /v1/users/me/eid/organizations/{regNo}/signers	Authorised signers
POST /v1/users/me/eid/organizations/{regNo}/signers/resend	Resend the invite
DELETE /v1/users/me/eid/organizations/{regNo}/signers	Remove a signer

Write operations are rate limited to ~30/min.

SSO proxy mode

With SSO_EID_PROXY_BASE_URL set, this data arrives through the SSO's proxy — Gerege App then needs no eID RP credentials of its own. Without it, the app's own EID_* credentials are used.

2. The proxy for apps

Gerege App exposes eID data to registered RPs read-only, so those apps never have to hold eID credentials.

Service	Path	Endpoints
eid-proxy (individual)	/v1/eid/*	summary · certificates · devices · activity
eid-org-proxy (organisation)	/v1/eid-org/*	organizations · organizations/{regNo}/signers

Individual and organisation services are grouped separately so an admin can enable or disable them independently.

Calling it

GET https://<issuer>/api/v1/eid/summary
Authorization: Bearer <the user's OAuth access token>

Authorization checks

For every request the middleware performs three checks:

1. Introspection (RFC 7662) — is the token active, and what is sub?
2. Scope check — load the client by the token's client_id and verify the service scope (svc:eid-proxy / svc:eid-org-proxy). The current grant is checked, so granting and revoking take effect immediately.
3. Gateway state — is the service enabled in the catalogue?

Condition	Response
No token / expired	401
Service not granted to the app	403
Service disabled in the gateway	503
Success	200 + data

How to grant it

Admin → Applications → the app → tick eid-proxy / eid-org-proxy → Save. An app without the tick gets 403.

Runtime toggle

Both services are registered in the API gateway catalogue. Enabling or disabling them in the admin gateway UI has a real effect on the routes — you can turn off individual eID while organisation eID keeps working.

Additional organisation operations

Endpoint	What
GET/PUT /v1/me/orgstamp/{regNo}	Organisation stamp image
DELETE /v1/me/orgstamp/{regNo}	Remove the stamp
PUT /v1/me/org-name-latin/{regNo}	Set the Latin name
GET/PUT/DELETE /v1/me/signature	Personal signature image
PUT /v1/me/latin-name	Personal Latin name

These belong to the assets module; images live in external storage and their URLs in the database.

Organisation registry

The org module is the platform's own organisation registry, separate from eID:

Endpoint	What
GET/POST /v1/org	List / create
GET /v1/org/lookup/{regNo}	Look up in the state registry (Gerege Verify / XYP)
GET /v1/org/{id}	Details
GET/POST /v1/org/{id}/members	Members
PUT/DELETE /v1/org/{id}/members/{userID}	Member role / removal

All tables are RLS-protected — a user only sees the organisations they belong to.