# Concepts — read this before you build

The few things to understand (not implement) so the integration is predictable.

## Authentication

Thomas is machine-to-machine, server to server. There is no end-user OAuth flow to build:
your backend holds one credential and calls Thomas on your users' behalf, and no person is
ever redirected to Thomas to sign in.

Your credential is an OAuth **client credential** — a client identifier and a secret.
Exchange them for an access token at `POST /oauth/token` using
`grant_type=client_credentials`, passing them either as HTTP Basic authentication or in the
request body. Thomas returns a bearer token that is valid for 10 minutes. There is no
refresh token: request a new one when the current token expires. Send the token in the
`Authorization` header on every request.

The secret is shown exactly once, when the credential is issued, and Thomas does not store
it. If you lose it, rotate the credential — nobody can look it up for you.

Credentials are least-privilege scoped — for example `assessment.send`, `result.read`,
`profile.read`, `report.aggregate`. No credential grants bulk access to raw scoring or the
item bank. Access is also checked against live state on every request rather than baked
into the token, so a change on the Thomas side takes effect on your next call rather than
when the token expires. A missing or invalid token returns `401 Unauthorized`.

## Identity & reconciliation

Email is the identity key. Send a person's email and Thomas resolves them to one identity —
the same person across every organisation. Matching is **exact and case-insensitive**.
Because this is psychometric data, Thomas never guesses with fuzzy or probabilistic
matches.

Resolution order:

1. **Match by email** — global and exact. One email, one identity, even across organisations.
2. **Then by HRIS id** — scoped to your company. The same HRIS id at another company is a
   different person.
3. **New, or flagged** — no match creates a new identity. If email and HRIS id point at
   different people, Thomas flags it for review, never a silent merge.

Identifiers Thomas understands: personal email, professional email, HRIS id (scoped to your
org), and partner reference (an opaque id scoped to your org). Prefer not to share emails?
Resolve by your own partner reference instead — same resolution, no personal data leaves
your system.

One identity, candidate to employee: someone resolved by personal email stays the same
person when a later hiring event adds their professional email or HRIS id, so their history
follows them.

Resolution is the `resolveIdentity` operation
([POST /v1/individuals/resolve](/docs/api/operations/resolve-identity.md)).

## How Thomas works

Your people take validated assessments; Thomas scores them and exposes the resulting
intelligence — behaviour profiles, connection and coaching — through the API. Raw scoring
and the item bank never leave Thomas; see [/trust.md](/trust.md).

## Where next

- [Quickstart use cases](/quickstart.md)
- [API reference](/api-reference.md)
- [Trust & compliance](/trust.md)