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](https://www.w3.org/TR/vc-data-model-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.

{% callout type="warning" %}
Claim values are not consistently typed. `trueidentity.valid` is a real boolean.
`sanctionscheck.is_pep` is the string `"Yes"` or `"No"`. `sanctionscheck.matches`
is a JSON-encoded string that needs decoding. Check the
[claim reference](/claims-and-credentials/claim-reference) for the shape of what
you are asking for rather than assuming.
{% /callout %}

{% callout type="info" %}
You verify the signature with the keys at
[JWKS](/oauth-oidc-reference/endpoints/jwks-json-web-key-set). You do not need to
call us to check a credential is genuine.
{% /callout %}

## 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](/oauth-oidc-reference/endpoints/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](/claims-and-credentials/credential-types) - what each one
  attests and how long it lasts.
- [Requesting claims](/claims-and-credentials/requesting-claims) - the syntax,
  and how to ask for the least you can.
- [Claim reference](/claims-and-credentials/claim-reference) - every claim there is.