OAuth 2.0 Tutorial

At Experian, we value the security of data above all. For applications to access an Experian API and/or act on a user’s behalf, they must be authenticated and authorised appropriately. Experian relies on the industry standard Open ID Connect protocol for granting access. You can authenticate to an Experian API using service accounts or end user accounts on their behalf.

Step 1: CONFIGURE APPLICATION

If you haven’t yet registered your first application, please visit our Quick Start Guide to get started and configure your application.  After you configure your application, a unique “Client id” and “Client secret” will be assigned to your application. Kindly make note of four credentials (i.e. User ID, Password, Client ID and Client Secret) to integrate them later with your code to authenticate and authorise against Experian APIs.

Sample:

Important noteDO NOT share your credentials value with anyone! 

 

Step 2: REQUEST ACCESS TOKEN

Once your application is properly configured, it's time to request an access token. An access Token is a JSON Web Token (JWT, aka the JOT token) which will contain the user/service account profile information together with expiry time and issuer details. The request access token can be used as a bearer token to invoke Experian APIs and allow your application to access products and APIs. A refresh token is also issued, so applications can renew expired access tokens.

Below is a sample from the Sandbox environment for the access_token request which includes token endpoint, headers and payload.

Request:

curl -X POST https://sandbox-uk-api.experian.com/oauth2/v1/token \
-H "Accept: application/json OR application/xml" \
-H "Content-Type: application/json OR application/xml" \
-H "grant_type : password" \
-d '{"username": "<USERNAME>","password":"<PASSWORD>",
"client_id":"<CLIENT_ID>", "client_secret": "<CLIENT_SECRET>" }'

 

Parameter Description
client_id
(Required)
client_id uniquely identifies your application and confirms that your application is participating in the  OAuth 2.0 flow. client_id is public facing and should be treated as your application's user name.
client_secret
(Required)
client_secret is a .secret key assigned to your application and should be treated as your application's password. Avoid sharing this key on any public forum or on client devices where users could decompile your code and access the secret.
Content-Type
(Required)
Refers to the payload type, currently we support  application/json and application/xml.
Username and Password
(Required)
Login credentials.

Accept (Optional)

Provide the acceptable data type i.e.: application/json or application/xml.
Grant-Type (Optional) Supported grant type is password.

 

Response:

Below is a sample response which includes status code and token information:

HTTP Status Code 200
{
  "issued_at" : "1509914612223", 
  "expires_in" : "1800",
  "token_type" : "Bearer",
  "access_token" : "<ACCESS_TOKEN>",
  "refresh_token" : "<REFRESH_TOKEN>"
}

 

Parameter Description
issued_at Refers to the unix epoch time elapsed in milliseconds.
expires_in Refers to the lifetime of the token in seconds.
token_type  Refers to the type of token.
access_token The access token for the client application must be kept secure and is valid for a limited period described by expires_in seconds.
refresh_token The refresh_token can be used to obtain a new access_token. This token must be kept secure and is valid for a limited period described by expires_in seconds.

 

Step 3: USING BEARER TOKEN

Once you've obtained an Access Token, you can start making authenticated API requests. This is accomplished by including an "Authorization" header with the Bearer token in your HTTP call to Experian’s API. Here is a sample HTTP request including the header value that includes the token:

'Authorization: Bearer $ACCESS_TOKEN’

For example, to make an API call as shown below, the access token has been passed as a Bearer token.

Request:

$ curl -v -X GET https://sandbox-uk-api.experian.com/risk/business/v1/registeredcompanycredit/99999999
       -H "Accept: application/json" \
       -H "Authorization: Bearer $ACCESS_TOKEN"

 

Step 4: ACCESS TOKEN REFRESH

You may obtain a new access_token, when the user’s access_token has expired by exchanging the refresh_token that is associated with the access_token.

Below is a sample request.

Request:

curl -X POST https://sandbox-uk-api.experian.com/oauth2/v1/token
  -H 'cache-control: no-cache' \
  -H 'client_id: <CLIENT ID>' \
  -H 'client_secret: <CLIENT SECRET>' \
  -H 'Accept: application/json' \
  -H 'grant_type: refresh_token' \
  -H 'refresh_token: <REFRESH TOKEN>'   

Response:

Status code 200
{
  "issued_at" : "1500914612223",
  "expires_in" : "7200",
  "token_type" : "Bearer",
  "access_token" : "$ACCESS TOKEN",
  "refresh_token": "$REFRESH TOKEN"
}

 

Step 5: TOKEN REVOCATION

If the client chooses to revoke a generated access and refresh tokens, it can be done by calling the revoke token endpoint. To revoke a token, a client application would make a request to the revocation endpoint as shown in the below sample in the sandbox environment.

Request:

curl -X POST https://sandbox-uk-api.experian.com/oauth2/v1/revokeToken\
  -H 'cache-control: no-cache' \
  -H 'client_id: <CLIENT ID>' \
  -H 'client_secret: <CLIENT SECRET>' \
  -H 'token: <REFRESH TOKEN>'  

 

Parameters Description
client_id
(Required)
The client id associated with the developer app.
client_secret
(Required)
The client secret associated with the developer app.
token
(Required)
The refresh token or access token to be revoked.

 

Response:

Status code 200

 

ERRORS  

Scenario Http Code Error Type Message
Expired Access Token 401 Unauthorized Access token is Invalid.
Client ID/Client Secret are missing 400 Bad Request The 'client_id' and 'client_secret' attributes are required.
Access token request with HTTP method other than POST 405 Method Not Allowed The requested method is not allowed.
Content-Type is missing or is not APPLICATION/JSON 415 Unsupported Media Type Content-Type header is unsupported.
Username/password is missing or blank 400 Bad Request The 'username' and 'password' attributes are required.
Username/password mismatch 401 Unauthorized Access is denied due to invalid username or password.
Incorrect Client ID/Client Secret  401 Unauthorized Access is denied due to invalid client id or client secret.
Authorization fails as account is not in active status 401 Unauthorized

Your account is in invalid state. For further assistance, please contact 

apisupport@experian.com

Regular expression attack, JSON threat and Spike arrest failure 401 Unauthorized Access to the requested resource is not allowed.
Default Authentication failure message 401 Unauthorized Access to the requested resource is not allowed.
IP range or Time of Day validation fails 403 Forbidden Access to the requested resource is forbidden.
Internal Server Error 500 Internal Server Error

Internal Server Error. If problems persist, please contact.

apisupport@experian.com

 

ENVIRONMENTS

Environment(s) Host URLs
Developer Sandbox  sandbox-uk-api.experian.com
UAT (User Acceptance Testing) uat-uk-api.experian.com
Production / Live uk-api.experian.com

 

OPENID PROVIDER CONFIGURATION ENDPOINT 

The OpenID Provider Configuration Endpoint is a public endpoint that provides configuration information for the OAuth client to interface with Experian using the OpenID Connect protocol.

Endpoint: https://uk-api.experian.com/.well-known/openid-configuration

The endpoint supports HTTP GET requests without authentication or parameter; for example:

$ curl -s https://uk-api.experian.com/.well-known/openid-configuration

The JWKS (jwks_uri) endpoint returns a set of public keys that are generated and rolled automatically by Experian. Clients can use this information to verify the integrity of asymmetrically-signed ID tokens. For information about other parameters please refer to OpenID Provider Metadata in OpenID Connect Discovery 1.0.

Sample curl for JWKS: curl -k https://uk-api.experian.com/oauth2/v1/keys