Scopes and the consent model

Scopes

Your service authenticates as itself with OAuth 2 client credentials and receives the scopes OFIS has approved for it.

Scope	What it allows	Who gets it
ofis:lookup	Non-personal status lookups: GET /api/v1/citizens/{fa_id}/	Every partner
ofis:assert	Signed assertions (POST /api/v1/assertions/), the linking code exchange, and webhook endpoints	Every partner that needs verified claims
ofis:enroll	Turn a Federal ID login into a Federal ID: POST /api/v1/enrollments/	Partners offering Sign in with Federal ID
ofis:issue	Issue new Federal IDs directly: POST /api/v1/citizens/	Restricted. Approved partners that onboard people on OFIS’s behalf
ofis:entitle	Grant, renew or revoke a membership entitlement for a Federal ID	Restricted. Apps that sell membership plans: the Federal Africa community platform today

There is also an internal ofis:admin scope for verification upgrades, suspension, revocation and audit. It is never issued to a partner.

What partners can learn

Without consent, holding a Federal ID lets you read its status (active, suspended, revoked), verification level (0 to 3), member state and membership tier. None of these identifies the person.

With consent, you can receive a signed assertion carrying any subset of six attributes: verified, verification_level, state_code, status, country, membership_tier. Nothing else is assertable, and nothing else is ever disclosed.

How consent works

Consent is per member, per partner, per attribute, recorded on the OFIS side the moment a member approves your app on the OFIS consent screen during the linking flow. Being granted verified does not imply country. If any requested attribute is not covered, the whole request is refused: there are no partial assertions.

Error	Meaning	What to do
consent_missing	No consent record for this member and your client	Send the member through linking
consent_revoked	The member withdrew your access from their portal	Stop asserting this identity; subscribe to consent.revoked
consent_expired	The consent record’s expiry passed	Ask the member to link again
scope_not_allowed	Consent exists but does not cover one attribute	Narrow the request, or link again asking for more

A member sees, on the consent screen, your app’s name, the Federal ID they are signed in as, and the exact attributes you ask for, with a note that you will never see their documents or other personal details and that they can revoke you later. Approval extends an existing consent record rather than replacing it.

The rules you agree to

• Verify assertions locally. A round trip to OFIS to double-check a signed assertion is a bug.
• Never call OFIS on your hot path. Two-second timeout, a circuit breaker, and your own cached state.
• Honour revocation. When consent is revoked, stop. When an identity is suspended, hide the badge.
• Show a badge only when verified is true and status is active. A revoked identity keeps its level.
• Store only a mirror: the Federal ID and the facts you were given. Never ask members for identity documents on OFIS’s behalf.