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 .
// Line breaks for legibility onlyhttps://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:
Now that you have a code you can redeem it for an access token.
POST /token HTTP/1.1Host: https://controller.sandbox.myoneid.co.ukContent-Type: application/x-www-form-urlencodedAuthorization: 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.1Host: https://controller.sandbox.myoneid.co.ukAuthorization: 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