Claims and credentials
What a credential is here, what a claim is, and why you rarely need the whole thing.
Two words do most of the work in this API, and they are not interchangeable.
A credential is a signed statement about a person: that their identity was verified, that a criminal history check came back a particular way, that they hold a current student enrolment. It is issued once, by us, and it does not change afterwards.
A claim is one field out of a credential: a family name, an expiry date, a yes or no. When a person shares a credential with you, they share the claims you asked for and nothing else.
That distinction helps us create a perfect world. Asking for trueidentity.credential gets you the credential. Asking for trueidentity.valid gets you true, and nothing else. Both answer "has this person verified their identity". Only one of them contains a person's name, date of birth and document summaries (no full numbers).
How the pieces fit
Credentials are W3C Verifiable Credentials 2.0, signed by our keys, and readable by anyone with our public key. The signature covers the whole credential.
Selective disclosure uses SD-JWT: rather than the credential carrying the values, it carries a hash of each one. The person sends you the values you asked for, and you check each against its hash. Anything they did not send, you cannot see - and cannot reconstruct.
So the credential can prove a great deal while telling you very little, and that is a property of the format rather than a promise we make.
Our own claim vocabulary is defined at {issuer}/baric/credential/tv-vocab/1.jsonld, which is the namespace the tv: prefixed fields inside a credential resolve against.
Getting them
Two routes, and they suit different things:
- OAuth OIDC. The person logs in with TrueVault and consents to share the claims you asked for. The claims arrive at the userinfo endpoint. Best when a person is present.
- The REST API. You ask for an identity, the person completes it in their own time, and a webhook tells you when it is done. Best when they are not.
Either way, the same credentials and the same claims. Only the delivery differs.
Where to go next
- Credential types - what each one attests and how long it lasts.
- Requesting claims - the syntax, and how to ask for the least you can.
- Claim reference - every claim there is.