Concepts
Subjects, templates, credentials, channels, distributions and events — and how they relate.
Six objects. Everything in the API is one of them, or a list of one of them.
| Object | Prefix | What it is |
|---|---|---|
| Organisation | org_ | The tenant. An API key belongs to exactly one, which is why no endpoint takes an organisation parameter. |
| Subject | sub_ | A person a credential is about, keyed by your externalId. A projection of your record, not a copy of your database. |
| Template | tpl_ / tpv_ | What a credential says and looks like. A template has versions; a version is published and then frozen. |
| Credential | cred_ | One credential held by one subject. Has a state, fields resolved at issue time, and a history. |
| Channel | cch_ | A credential on one wallet. Apple Wallet is a signed file; Google Wallet is a record held by Google. |
| Distribution | — | One act of handing a credential over: a link, a QR, an email, an NFC tag. |
Credential states
A credential is in exactly one of five states: draft, issued, suspended, expired, revoked. Suspension is reversible; revocation is not. Expiry happens on its own, from the validity rule on the template version or the expiresAt given at issue time.
Channel states
Each channel carries its own state — pending, provisioned, installed, stale, failed, removed — because a credential being valid and a phone actually holding it are two different facts. A credential in issued with a channel in failed is a real situation, and the API says so rather than averaging the two.
Achievements and awards
Nomi Academic replaces the template with an achievement: what was earned, its criteria, its skills and its level. Awarding one issues an ordinary credential backed by that achievement, with a public verification code from the moment it exists. Everything after that — revoking, suspending, expiry, webhooks — is the same lifecycle.