Most people building against this API are doing it with a coding assistant. That
works better when the assistant is reading our documentation rather than
recalling a generic OAuth tutorial, so this page gives it the addresses and a
starting prompt for each of the integrations people build most.

## Tell it which integration to build

Assistants reach for the REST API, because a REST API is what an API looks like
to them. For most of what people build here that is the longer road, so say
which one you want in the prompt rather than letting it choose.

**Default to the OIDC redirect flow.** If the person is in a browser and you
want them signed in at the end, it is the shortest path to a verified identity,
and any OIDC library already speaks it.

**Reach for the Identity REST API when the flow will outlive the person's
visit.** Two cases:

*   **Long-running checks.** An ACIC police check can take days to come back.
    Nobody is going to sit on a redirect waiting for it, so create the request,
    let them complete it in their own time, and take the result on a webhook.

*   **Asynchronous integrations.** A mobile app, a third-party plugin, a
    back-office process - anywhere there is no browser session to redirect and
    no user sitting in front of you.

They read the same credentials underneath, so this is a question of shape rather
than of capability, and plenty of integrations use both.

## Point it at the right sources first

Three addresses matter, and an assistant that has them will not guess:

| Address | What it is |
|---|---|
| `/llms.txt` | An index of every page, each linking to its markdown |
| `/{page}.md` | Any page's markdown source - add `.md` to the address |
| `/api/v1/docs/spec` | The OpenAPI description of the REST API |
| `/.well-known/openid-configuration` | Live OIDC metadata, including `true_claims_supported` |

Every page also carries an **Ask AI** control in the header that hands that
page's markdown to an assistant for you.

{% callout type="warning" %}
Assistants have strong opinions about OAuth from a decade of other people's
tutorials, and will quietly apply them here. Give it these addresses and ask it
to check the specification before writing, rather than after you find the bug.
{% /callout %}

## Log people in with TrueVault

The most common integration, and the one to try first: a "Continue with
TrueVault" button that returns a verified identity rather than just an
authenticated session.

```text
Read https://developers.truevault.com.au/llms.txt, then the OIDC pages under
oauth-oidc-reference.

Build a "Continue with TrueVault" login for <your framework>.

Requirements from the specification, not from memory:
- Authorization Code flow with PKCE. code_challenge_method must be S256.
- Sandbox issuer is https://sandbox.truevault.com.au. Read the discovery
  document at /.well-known/openid-configuration rather than hardcoding endpoints.
- Validate state and nonce. Verify the id_token signature against the JWKS.
- Ask only for trueidentity.valid unless I tell you otherwise. Do not request
  birth_date or the full credential.

Show me the authorization request, the token exchange and the userinfo call,
and tell me which claims each returns.
```

## Verify someone when there is no browser to redirect

For the asynchronous case - an app, a plugin, a back-office process. Create a
request, send them the link, and receive a webhook when they finish, however
long that takes.

```text
Read https://developers.truevault.com.au/llms.txt, then rest-api-reference and
the webhook page under it.

Build an identity verification flow for <your framework> using the REST API.
Do not use the OIDC redirect flow for this - there is no browser session to
redirect, and the person may finish hours after my request.

- Base URL https://api.sandbox.truevault.com.au/api/v1
- Every call needs Authorization, X-Tenant-Id and X-Request-Timestamp headers.
  Send X-Correlation-Id too and log it.
- POST /identity/request, then handle the webhook, then
  GET /identity/response/{access_request_code}/{identity_session_code}.
- Verify the X-Webhook-Signature HMAC before trusting the payload.
- Choose a ruleset deliberately and tell me why you chose it.

Handle the case where the person never finishes.
```

## Run a background or right-to-work check

Checks are obtained rather than read. Which integration depends on how long you
are willing to keep the person waiting: an essential claim in the OIDC flow gets
them the credential there and then, while a REST request suits a check that may
take days to come back.

```text
Read https://developers.truevault.com.au/claims-and-credentials/requesting-claims.md
and .../credential-types.md.

I need <an ACIC criminal history check | an Australian right-to-work check> as
part of onboarding.

- Recommend an integration first. Use the OIDC flow with an essential claim if
  the person can finish it while they are with me; use the REST API with the
  matching ruleset and a webhook if the result may take days.
- Either way the check must be obtained, not just read back.
- Tell me which ruleset is appropriate and what the person will be asked for.
- Tell me how long the resulting credential is valid, and what my code should do
  when it expires.
- Ask for the narrowest claims that answer my question.
```

## Verify a credential somebody presents

You do not need to call us to check a credential is genuine.

```text
Read https://developers.truevault.com.au/claims-and-credentials/introduction.md
and the JWKS endpoint page.

Write a verifier for a TrueVault credential in <your language>.

- Verify the signature against the JWKS at the issuer.
- It is an SD-JWT: check each disclosed value against its hash commitment.
- Check validity dates and the status list for revocation.
- Explain what an expired credential means versus a revoked one.

Do not call the TrueVault API to do this. Verification is offline.
```

## Ask for less than you were going to

Worth running against an integration you have already built.

```text
Read https://developers.truevault.com.au/claims-and-credentials/requesting-claims.md
and .../claim-reference.md.

Here are the claims my integration currently requests: <paste them>.

For each one, tell me whether a narrower claim would answer the same question,
and what I would stop receiving. Flag anything that returns personal data about
people other than my customer.
```

## Two things to check in whatever it writes

Assistants get these wrong here, because both differ from the conventions they
have learned elsewhere:

- **Claim value types are not uniform.** `trueidentity.valid` is a boolean,
  `sanctionscheck.is_pep` is the string `"Yes"`, and `sanctionscheck.matches` is
  a JSON-encoded string that needs decoding. Generated code tends to assume all
  three are booleans.
- **`essential` obtains a credential.** It is not a validation flag. An assistant
  that treats it as "required field" will not understand why the journey got
  longer, or why it cost something.
- **It will drift back to the REST API.** Left to itself an assistant writes the
  integration it has seen most often. If you asked for the redirect flow and the
  answer is full of `X-Tenant-Id` headers, it has changed its mind without
  telling you.