Credential Verification API
A machine-readable way to ask whether an IAWA credential is genuine and current. It answers one question at a time about a number you already hold, and a change feed tells you what has moved since you last looked.
Getting a key
Write to support@iawausa.org with the name of your organization, a technical contact, and how you intend to use the API. We issue a key per environment. The key is shown to us once when it is created and sent to you directly; we cannot recover it afterwards, so a lost key is replaced rather than retrieved.
Authentication
Present the key as a bearer token over HTTPS. Keys are never accepted in a query string, where they would end up in logs and browser history.
curl -H "Authorization: Bearer iawa_live_..." \
https://dev.iawausa.org/api/v1/credentials/IAWA-XXXXXXX
Look up one credential
GET /api/v1/credentials/{number} - scope credential:read
{
"credential_number": "IAWA-137SV9J",
"status": "ACTIVE",
"is_current": true,
"holder_name": "Dana Whitfield",
"issued_at": "2026-09-26T06:58:27Z",
"expires_at": "2027-09-26T06:58:27Z",
"endorsements": [],
"checked_at": "2026-09-26T07:31:02Z"
}
is_current is the field most callers want: it is true only
when the credential is active and its term has not run out. Expiry is
evaluated when you ask, not by a nightly job, so the answer is never stale
on our side.
status is one of:
ACTIVE- certified and within the term.EXPIRED- the term has run out. The person may be part way through a refresher.SUSPENDED- temporarily not in good standing.REVOKED- permanently withdrawn.
A number we have never issued returns 404 with
"status": "NOT_FOUND". A revoked credential and a number that
never existed are different answers, and we give both honestly.
The change feed
GET /api/v1/credentials?updated_since={RFC 3339} - scope credential:feed
Returns credentials whose standing or term changed after a moment, oldest
first, up to 200 per page. Use the next_since value from a
response as the updated_since of your next call; when the list
comes back empty, you are caught up.
{
"credentials": [ ... ],
"next_since": "2026-09-26T07:12:44Z",
"checked_at": "2026-09-26T07:31:02Z"
}
Caching
We expect you to cache rather than call us on every page view. Three rules keep a cache honest:
- Never treat a positive answer as valid past its
expires_at. - Re-check any credential you rely on at least once every 24 hours.
- Poll the change feed at least hourly.
Expiry you can compute yourself; suspension and revocation are the cases a cache gets wrong, because they happen between terms and without warning. That is exactly what the change feed is for. An hourly feed poll plus a daily re-check bounds how long you can be acting on a withdrawn credential.
Rate limits
Each key carries a per-minute limit, returned on every response as
RateLimit-Limit, RateLimit-Remaining and
RateLimit-Policy. Exceeding it returns 429 with
Retry-After. Tell us what you need and we will set the limit
to match.
Errors
401 invalid_key- missing, unknown, revoked or expired key. The response does not say which; ask us if a key stops working.403 insufficient_scope- the key does not carry that scope.404 NOT_FOUND- no credential carries that number.429 rate_limited- slow down and retry after the stated interval.400 bad_request- a parameter is missing or malformed.
What the API will not do
There is no endpoint that lists credentials or looks a person up by name or email, and no batch lookup: you can check a number you already hold, and nothing more. Responses never carry training history, scores, attempts, photographs, payment data, or contact details. If a fact is not good enough to show a stranger holding the number, it is not in the API.
Access is read-only. Nothing outside IAWA changes a credential.
Versioning
The path carries the version. Within v1 we only add fields;
anything that would break a caller becomes v2, and
v1 keeps working for a stated period after that.