AAR ↔ Pathos Integration — Process Overview

Three systems, one direction of trust

AAR is the coordinator: it owns the applicant record and the overall clearance decision. Pathos runs the background check and the training, and reports status on each. Crucially, AAR only ever reads from Pathos; it does not expose an API back. Least privilege by default.

Coordinator

AAR

Owns applicant record
& clearance decision

1 · AAR fetches the data

2 · webhook on status change

Pathos

Background Check

/background-check/*

Pathos

Education / Training

/education/*

◆ AAR pulls; Pathos pushes. AAR is the only system that initiates queries across the boundary. Pathos exposes a small read API plus webhook notifications, and never needs to read from AAR.

AAR

The coordinator

Initiates every cross-boundary query. Aggregates both checks. Decides clearance. Exposes no API outward.

Background Check

Reports pass / fail

Runs the check, returns an array of background-check records with a status phrase and a human-readable description.

Education

Reports complete / incomplete

Delivers the prescribed training, returns enrollments per cycle, each carrying the courses behind it.

Asynchronous by design: webhooks first, polling always available

Background checks and training take hours or days, so AAR never blocks on them. Both delivery models are fully supported; choose whichever fits your timeline. webhooks preferred polling every 5 min

AAR registers the applicant with you

AAR initiates the vendor-side process for an applicant it already owns.

The applicant completes your process

Over hours or days. AAR is not waiting on the wire; it has moved on.

Preferred: you fire a webhook

On a significant status change you POST a minimal, signed notification. AAR then calls your lookup endpoint to pull the full record. Webhook safety →

Alternative: AAR polls your lookup

On a schedule (default every 5 minutes). No extra endpoint needed; the same lookup serves both paths. At the expected scale this is perfectly acceptable.

Matching an applicant across systems

Applicants are the same people in different databases. The shared identifier is email, strengthened by a second factor and a verified-secondary-email mechanism that absorbs the "different email per system" problem.

Primary identifier

Email, matched carefully

Case-insensitive. Lowercase both sides before comparing.
Dots are significant. john.doe@ is not johndoe@. Ignoring dots is Gmail-specific; match the normalized string exactly.

Second factor

Plus date of birth

Email alone is not a strong enough match for a background-check context. A positive identity match requires email and date of birth to agree. Chosen over address (too many spellings) and over SSN (heavier storage and compliance, unjustified here).

Verified secondary email, a first-class part of the process, entirely on AAR's side.
Applicants often sign up to different systems with different addresses. AAR lets an applicant register and verify one secondary email, then matches on either address. For you this means nothing extra: you store and match a single email. When a primary-email lookup misses, AAR simply re-queries your lookup with the verified secondary email. SSO was considered & deferred

Why not single sign-on? A tempting alternative to matching emails at all is SSO: an applicant clicks a link in AAR that drops them into Pathos already signed in, so they never create a separate Pathos account and the two identities link automatically. It is buildable, with a short-lived (about 30 seconds), single-use redirect token: AAR hands the applicant off to Pathos carrying a signed token, Pathos calls back to a small AAR endpoint to verify that token and learn who the applicant is, then opens their session.

We deferred it for three reasons. It assumes a known starting point, and we can't guarantee applicants begin at AAR, or in what order they touch each system. Creating an account on each system is a minor step, not a real burden. And it would force AAR to expose a verification endpoint, which breaks the "AAR exposes nothing outward" stance from the model above. The verified secondary email solves the real problem (different emails per system) without any of that. If the AG later wants a true SSO experience, it is a clean follow-on to scope separately.

What we're asking Pathos to build

These are the endpoints we're proposing Pathos build and expose to AAR: a deliberately small surface, mirrored across both Pathos systems. Everything below is already live in our reference implementation, so you can read the schemas and try each call before writing any code.

Lookup

One call, full picture

GET /{vendor}/applicants/{id} GET /{vendor}/applicants?email=&dateOfBirth=

By internal ID, or by the two-factor pair (both required). Returns identity and this system's records. 404 on no match

Webhooks

Subscribe & notify

POST /{vendor}/webhooks/subscriptions

Register an AAR callback target, separate production sandbox targets, separate signing secrets. Payloads stay minimal and signed.

Key rotation

Self-service, gated

POST /{vendor}/keys/rotate

Mint a new key with the current key plus a separately held client secret. No admin portal required.

Background Check returns

An array of checks

An applicant may undergo more than one check over time, so the response is an array. AAR reads the most relevant entry but keeps the full list as evidence. Each record is a status phrase (not_started · in_progress · approved · rejected) plus a description. No numeric score.

Education returns

Enrollments, then courses

Training likely renews periodically, so each cycle is its own enrollment with an overall status and the courses behind it. This is the shape we are least certain about: the grouping name, renewal cadence, and course-level detail are exactly where we want your input.

Authentication & security

A single, direct, server-to-server trust relationship between AAR and Pathos, both working directly with the Louisiana AG, our common client. The baseline below is a starting point, not a mandate. We're genuinely open to other approaches; we just need to settle the decisions early, before they turn into costly rewrites.

Baseline

Bearer API key, or OAuth

Bearer API key in the Authorization header. Sufficient for this single, direct, server-to-server trust, and our recommended baseline.
OAuth 2.0 client-credentials is a fine alternative if you prefer it. Buys built-in token expiry and tighter scope, at the cost of more moving parts.

Whichever you choose: HTTPS only, scoped to what AAR needs, every use logged for audit.

Key format & storage

Prefixed, long, hashed

Prefixed & random: pathos_bg_… pathos_edu_…
32+ bytes of entropy; bcrypt-hashed at rest, never stored in plaintext.

Rotation

Two-secret gate, no portal

Rotating requires the current API key and a separately held client secret. An intercepted key alone cannot rotate itself and lock out the legitimate user.

POST /keys/rotate · Bearer + clientSecret

Cadence & rotation

Regular rotation, no downtime

Keys carry an expiration and rotate on a set cadence: 90 days, 120 days, or whatever we settle on together.
Let AAR register more than one active key at a time, so a new key can be brought online and confirmed before the old one is retired. No cutover window to coordinate.
On suspected compromise, revoke immediately, out of band.

Webhook safety. Sign each request (HMAC over the raw body) with a timestamped signature and a freshness window to stop replay. Send a stable eventId so AAR can de-duplicate. Retry non-2xx with backoff, and provide a way to replay a missed event. Separate sandbox and production signing secrets.

A working reference of the proposed API

To make the proposal concrete, we built a working reference of it: our own implementation of the contract above, so Pathos can see and exercise the exact shapes we're asking for. Both systems are combined under separate path prefixes for testing. Open the reference and use the pre-built test applicants below.

First, what is OpenAPI? OpenAPI is the widely-used standard for describing an HTTP API in a single machine-readable file: every endpoint, its parameters, and the exact shape of every response, written down once. Two things come from it. The interactive API reference (the Open API Reference button) is generated directly from it, so the docs can never drift from the API they describe. And the raw file itself (the OpenAPI spec) can be handed to tools like Postman or Insomnia, or used to auto-generate a typed client in your language, so Pathos never hand-copies endpoints from a document. Both are linked right here.

Email	Date of birth	Background check	Education
jane.smith@example.com	1990-04-12	approved	complete
john.doe@example.com	1985-11-03	in_progress	incomplete
not.started@example.com	1998-07-22	not_started	not_started
rejected@example.com	1979-02-28	rejected	complete

What's real

You can exercise it now

Live lookups by ID and by email + DOB, with real Zod validation and 404s.
Webhook /test returns the exact signed payload; recompute the HMAC to verify it.
Key rotation mints a real prefixed, random key.

What's illustrative

Honest limits of a demo

Auth is documented, not enforced here, so "Try it" is frictionless.
Subscriptions and rotation are echo-back / ephemeral; nothing is persisted in this demo.
The webhook endpoint previews the signed request; it does not deliver to a live URL.

Open the API Reference →