# Concepts — read this before you build

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

## Authentication

Thomas uses machine-to-machine API keys, server to server. There is no end-user OAuth flow
to build: your backend holds one key and calls Thomas on your users' behalf. Send the key
as a bearer token on every request.

Keys are least-privilege scoped — for example `assessment.send`, `result.read`,
`profile.read`, `report.aggregate`. No key grants bulk access to raw scoring or the item
bank. Keys are issued when you sign in; the public docs never issue one, so keep yours
server-side. A missing or invalid key 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)