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
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.
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&scopes=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 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 in the token response. 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 return_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 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 .
We are unable to verify the user. This 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.
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"}