| name | nafath-yakeen-basics |
| description | Keep the agent from inventing fake Nafath or Yakeen endpoints. Explains the approval path, the integration model, and which behaviors you cannot ship without a credential. |
Nafath and Yakeen Identity Onboarding
When this skill activates
Use this skill whenever the work proposes verifying a Saudi citizen or resident identity, issuing a government-backed trust decision, or linking an account to a national ID.
Also use it when the work touches Nafath login, National Single Sign-On, Absher-backed authentication, Yakeen/Yaqeen attribute verification, biometric identity confirmation, KYC onboarding, national ID/Iqama handling, or identity-provider fallback logic.
Operational warning
Do not generate client code against imagined Nafath or Yakeen endpoints. Neither service offers open self-service API keys. Integration requires an approval workflow, sponsor-bound credentials, and sandbox onboarding. Treat any unreferenced URL or token as a fabrication until a human confirms it.
Compliance baseline
- Identity verification is an onboarding concern that must be planned before coding — not a library to drop in.
- Nafath provides authentication signals; it does not provide arbitrary citizen data.
- Yakeen provides attribute verification through authorized service providers — treat it as a data lookup gated by contractual scope, not an open directory.
- National IDs and Iqama numbers are personal data. PDPL rules from
pdpl-basics apply in addition to this skill.
- A verification decision must store the minimum durable result: provider, subject reference, decision, timestamp, assurance level if supplied, expiry/reverification policy, and evidence id. Do not persist raw returned attributes by default.
- Every identity flow needs a business owner for provider approval, credential ownership, failure handling, and user support.
Hard stops
- Do not invent base URLs, OAuth clients, request payloads, random-number flows, or callback contracts.
- Do not treat a timeout, pending status, or user-cancelled approval as verified.
- Do not accept a client-submitted national ID as proof of identity. It is only an input to an approved provider flow.
- Do not use a mock that returns
verified: true unless it is isolated to test/dev and impossible to deploy to production.
Engineering guidance
Before writing code
- Confirm the business has, or is actively obtaining, a Nafath or Yakeen engagement. If not, stop and route the team to apply before sprinting on code.
- Name the authorized service provider or government channel being used. Generic "call Nafath" stories are a red flag.
- Specify which attributes are actually required. Most flows need a verified identity signal, not a full profile.
- Decide the fallback policy up front: retry, pending review, branch visit, or rejection. The fallback must not silently reduce assurance.
While integrating
- Keep credentials out of the repository. Reuse the guidance in
secrets-baseline for handling and rotation.
- Isolate the identity provider client behind a thin adapter so test fixtures, error handling, and retries do not leak into feature code.
- Never cache raw identity attributes longer than the flow that needs them. Store the verification outcome, not the source attributes, whenever possible.
- Keep provider callbacks idempotent. Duplicate approvals, delayed callbacks, and mobile-app retries should update the same verification attempt.
Error and fallback handling
- Treat a failed identity verification as a hard stop for the privileged flow. Do not silently fall back to an unverified path.
- Provide a clear user-facing message in both Arabic and English explaining that verification is pending or rejected.
- Log identity decisions with enough context to audit, but without embedding the raw national ID in application logs.
- Rate-limit verification attempts and avoid retry storms against the provider.
Related skills
- Use
pdpl-basics for national ID, Iqama, biometric, profile, and verification-result storage.
- Use
secrets-baseline for provider credentials, callback secrets, certificates, and signing keys.
- Use
auth-isolation when verified identity unlocks privileged account actions or admin review.
References
- Read
references/nafath-yakeen-approval-steps.md for the approval and onboarding sequence.
- Read
references/nafath-yakeen-do-not.md for common hallucinations to flag in generated code.
Version: 0.2.0 · Last verified: 2026-04-24 · Status: draft
Engineering guidance, not legal advice. Verify each rule against the official sources below.
Sources
