Authentication
Two mechanisms that are easy to confuse
An API key says which system is calling. A verifiable credential says which tier a third party is entitled to read. Treating the second as a variation of the first is the most expensive mistake in a passport integration.
- Scheme
- Bearer
- Scoped by
- Env + capability
- Third parties
- W3C credentials
Definition
How do you authenticate against the passport API?
Your systems present a scoped bearer key, issued per environment and per capability, over HTTPS. Third parties reading restricted passport tiers do not use keys at all: they present a W3C Verifiable Credential issued by a party the access policy trusts, and the resolver returns the tier that credential entitles them to.
The separation matters because the two have different lifecycles. A key belongs to your integration and rotates on your schedule; a credential belongs to a recycler or an authority and is revoked when their permit lapses, not when your contract does.
Requests
Presenting a key
curl https://api.circuleid.com/v1/passports/01/09506000134352 \
-H "Authorization: Bearer $CIRCULEID_API_KEY"
# Scope errors are explicit rather than a bare 403:
# {
# "error": "insufficient_scope",
# "required": "passports:read:restricted",
# "granted": ["passports:read:public", "events:write"]
# }Comparison
Keys and credentials side by side
| API key | Verifiable credential | |
|---|---|---|
| Authenticates | Your systems | A third party reading a passport |
| Issued by | CirculeID, to your organisation | A party the access policy trusts |
| Scoped by | Environment and capability | What the credential asserts |
| Revoked when | You rotate or a key leaks | A permit or accreditation lapses |
| Verified by | Us, on each request | Anyone, cryptographically |
| Lives in | Your secret manager | The holder’s own wallet or system |
Practices
What we recommend
One key per service
So a leak has a blast radius you can describe in a sentence.
Least privilege scopes
An issuing pipeline never needs read access to restricted tiers.
Environment separation
Sandbox keys cannot reach production passports, by construction.
Overlapping rotation
Both keys valid during the change, so rotation is not a deployment race.
Short-lived where possible
Expiry on keys used by ephemeral workloads limits how long a leak matters.
Audit before you assume
The log shows what a key did while valid — the basis for judging exposure.
Answers
Frequently asked questions
What is the difference between an API key and a credential here?
An API key authenticates your systems to CirculeID and is scoped to what your organisation may do. A Verifiable Credential authenticates a third party — a recycler, a repairer, an authority — to a passport, and decides which tier they receive. Keys are ours to issue; credentials come from whoever the access policy trusts.
How should keys be scoped?
Narrowly, and per service. An issuing pipeline needs write access to passports and nothing else; a storefront needs read access to the public tier and nothing else. Scoping per capability means a compromised key in one service does not expose restricted data held for another.
Are sandbox and production keys interchangeable?
No, deliberately. Keys carry their environment, so a sandbox key cannot touch production passports and a production key cannot be used accidentally in a test harness. Passports are long-lived public artefacts; an accidental production issue is not something you can quietly delete.
How is key rotation handled?
Keys can overlap: issue the new one, deploy it, then revoke the old one, with both valid in between. Rotation without an overlap window means a deployment race, which is how organisations end up never rotating at all.
What happens if a key leaks?
Revoke it immediately; revocation takes effect on the next request rather than at a cache expiry. The audit log shows what that key did while it was valid, which is what you need in order to judge exposure — and the reason scoping keys narrowly makes that judgement short.
Next step
Get a sandbox key
Scoped to one capability, in an environment that cannot touch anything real.