TrueVault OIDC API

Standard OpenID Connect, with a verified identity behind the login. Start here for the OIDC integration.

This is OpenID Connect as you already know it - Authorization Code flow with PKCE, a discovery document, an id_token, a userinfo endpoint. The difference is what sits behind it. When someone signs in with TrueVault for the first time, they prove who they are before the code comes back to you, so the session you end up with belongs to a verified person rather than to whoever typed in an email address.

Anything that speaks OIDC can talk to us. If you have a library, use it.

What you get that a standard provider does not#

• A verified person, not an account. The first sign-in takes them through document and biometric checks. You get the result, not the documents.

• Claims you can rely on. trueidentity.valid is checked against a ruleset, not self-asserted. See Claims and credentials.

• Checks obtained on demand. Mark a claim essential and the person is taken through getting the credential - a police check, a right-to-work check - as part of signing in. See Requesting claims.

• Nothing to store. You can ask for a yes or no and receive only that. The identity documents never reach your systems, so they are not yours to lose.

Is OIDC the right integration for you?#

Start here. The redirect flow is the shortest path to a verified person, and it is the one most integrations want.

The two are not exclusive, and they read the same credentials underneath. A common shape is OIDC for sign-in, then the REST API later on when a check has to be renewed and the person is not around.

Before you start#

• A client_id, and a client_secret unless you are configuring a public client. Create your first client walks through the dashboard.

• Your redirect_uri, registered against that client. It has to match exactly.

• The rulesets you intend to request, enabled on the client. Asking for one that is not enabled fails the authorization request.

• PKCE. It is mandatory here, including for confidential clients, and code_challenge_method must be S256 - plain is not accepted.

• HTTPS on your redirect URI in production.

How the flow runs#

1. Generate a code_verifier and its S256 code_challenge, plus a state and a nonce. Keep all three in the user's session.

2. Redirect to /oauth/oidc/authorize with those, your scopes, and the claims you need. Or, if you have a client_secret, push them to us first and redirect with only a request_uri - see Pushed authorization requests.

3. We take the person through identity verification, or straight to a consent screen if they already hold what you asked for.

4. They come back to your redirect_uri with a code and your state. Check the state matches before you do anything with the code.

5. Exchange the code at /oauth/oidc/token, sending the original code_verifier. Validate the id_token signature against the JWKS and check the nonce.

6. Call /oauth/oidc/userinfo with the access token for the claims themselves.

The user journey draws the same sequence, including what the person sees at each step.

Keep the request off the URL#

If your client has a client_secret, we recommend starting each login with a pushed authorization request: POST the parameters to us from your server, then redirect with only your client_id and the request_uri we return. Two things get better:

• Nobody can edit the request on the way through. The claims, email, phone and ruleset you asked for never appear in the browser, a proxy log or a Referer header. We only act on what your server pushed with your secret attached.

• The URL stops growing. The claims parameter is JSON, and a dozen claims make a direct authorize URL several hundred bytes that some email clients, SMS gateways and proxies truncate. A pushed one is under 200 bytes however much you ask for.

It is optional, and a public client cannot use it because there is no secret to authenticate the push. The rest of the flow is unchanged either way.

A minimal authorization request#

Enough to sign someone in and learn nothing else about them:

GET /oauth/oidc/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyour-app.com%2Fcallback
  &scope=openid
  &state=RANDOM_STATE
  &nonce=RANDOM_NONCE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256
  &claims=%7B%22true%22%3A%5B%22trueidentity.valid%22%5D%7D
Host: sandbox.truevault.com.au

That claims parameter, decoded, is {"true":["trueidentity.valid"]} - one boolean saying the person met the ruleset. Ask for more only when you have a reason to hold it.

Where to go next#