TrueVault Identity Manager

Build with AI

Prompts for the integrations people build most, and how to point an assistant at the right sources.

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:

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:

AddressWhat it is
/llms.txtAn index of every page, each linking to its markdown
/{page}.mdAny page's markdown source - add .md to the address
/api/v1/docs/specThe OpenAPI description of the REST API
/.well-known/openid-configurationLive 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.

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.

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.

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.

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.

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.

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: