Verify a User

This guide will show you how to verify a user and retrieve their data.

It applies to the following products:

Age Check, Age Verification, Age Assure
Sign-in, Sign-in Refresh, Sign-up, Sign-up Plus
ID Live, ID Check, ID Proof, ID Assure, ID Scan, ID Scan - RTW, ID Scan - DBS

1. Before you begin

Before you can verify a user you need a client_id and client_secret .

They can be obtained from either the OneID Console or by contacting Support.

To get access to the OneID Console you have to complete our form. Once you have access to the OneID Console, you can follow the Create a Client guide.

A given client_id and client_secret can only be used in one environment, production or sandbox.

2. Send the user to OneID

User verification starts with you sending the user to OneID.

The URL to send them to will depend on the OneID environment (production or sandbox) and what user data (claims) you want us to return.

In this example, the client is requesting the users profile (name) and date_of_birth .

Please note:

On mobile devices, the OneID journey must be opened in the device’s default browser; in-app browsers are not supported
The OneID journey cannot be displayed within an iframe on any device

// Line breaks for legibility only https://controller.sandbox.myoneid.co.uk/v2/authorize? client_id=1-2-3-4-5& response_type=code& scope=openid profile date_of_birth& redirect_uri=https://example.com/my-return-path& state=1234

Parameter	Required/Optional	Description
`client_id`	required	The ID that OneID assigned to your application.
`response_type`	required	Must be `code` .
`scope`	required	A space separated list of scopes (data) that you want.
`redirect_uri`	required	Determines where the OneID server redirects the user after the user completes the authorisation flow. The value must *exactly* match one of the authorised redirect URIs that are configured on your client. The URI must be https.
`state`	recommended	A value included in the request that is also returned as a query param on the `redirect_uri` when we redirect the user back to you. It can be a string of any content that you wish. A randomly generated unique value is typically used for preventing cross-site request forgery attacks. The value can also encode information about the user's state in the app before the authentication request occurred. For instance, it could encode the page or view they were on.

3. We verify the user & redirect them back to you

We'll attempt to verify the user and data that you want.

We'll then redirect them to the redirect_uri that you provided.

4. You handle the returned user

There are two cases you need to handle; success and error.

Success

The URI the user is redirected to will include the query params code and state .

e.g. If you had set the redirect_uri to https://example.com/my-return-path and the state to 1234 then we would redirect the user to:

https://example.com/my-return-path? state=1234& code=eyJhbGciOiJkaXIiLCJjdHkiOiJKV1QiLCJlbmMi...

Now that you have a code you can redeem it for an access token.

POST /token HTTP/1.1 Host: https://controller.sandbox.myoneid.co.uk Content-Type: application/x-www-form-urlencoded Authorization: Basic {token} grant_type=authorization_code &code=eyJhbGciOiJkaXIiLCJjdHkiOiJKV1QiLCJlbmMi...

The {token} in the Authorization header is constructed like base64(client_id:client_secret) .

i.e. If your client_id is 1-2-3-4-5 and your client_secret is 6-7-8-9-0 then your {token} would be MS0yLTMtNC01OjYtNy04LTktMA== .

This example shows a successful /token response:

{ "access_token": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUZrd0V3WUhLb1...", "token_type": "Bearer", "expires_in": "1800", "id_token": "eyJhbGciOiJQUzI1NiIsImtpZCI6ImhWVktTd..." }

Error

The URI the user is redirected to will include the query params error , error_description , error_oneid and state .

An error could have been because the user decided to cancel the process, or we might have experienced an internal error. A list of errors can be found on the errors reference page.

You will not be able to retrieve the user's data when there is an error.

5. Retrieve the user's data

After you have got the access_token from step 4 you can retrieve the user's data.

Depending on what data you requested will depend on what API(s) you need to call.

The majority of data is available from the userinfo API.

The Journey API Reference contains the available APIs.

GET /userinfo HTTP/1.1 Host: https://controller.sandbox.myoneid.co.uk Authorization: Bearer {access_token}

Response:

{ "sub": "7d4d6752-54d6-4b4f-9c6a-c6f4e806f54f", "name": "John Smith", "given_name": "John", "family_name": "Smith", "birthdate": "1950-01-02" }

6. Finish

You have successfully completed the Verify a User guide.

Here is some more documentation that you may find useful:

Testing - a list of testing scenarios
Breaking Change Policies

Last updated on

Was this page helpful?