OAuth 2.0 Tutorial

OVERVIEW

At Experian, we value the security of data above all. 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.

OAuth 2.0 is an authorization framework that allows third-party services to make requests on behalf of a user without accessing passwords, and other sensitive information. Experian API’s use OAuth 2.0 protocol for authentication and authorization. Experian API’s supports the OAuth 2.0 two-legged authentication code flow.

If you haven’t registered your first application yet, please visit our Quick Start Guide to get started and configure your application. 

 

ENVIRONMENTS

Environment(s)

Host URLs

Developer Sandbox

sandbox-us-api.experian.com

UAT (User Acceptance Testing)

uat-us-api.experian.com

Production

us-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://us-api.experian.com/.well-known/openid-configuration

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

$ curl -s https://us-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://us-api.experian.com/oauth2/v1/keys

Step 1: 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). The JWT token 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 API’s and allow your application to access products and API’s. A refresh token is also issued, so applications can renew expired access tokens.

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

curl -X POST https://sandbox-us-api.experian.com/oauth2/v1/token \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -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 which confirms that your application is participating in the OAuth 2.0 flow. This public facing ID should be treated as your application's user name.

client_secret

(Required)

client_secret is a secret key assigned to your application, this 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)

Developer’s login credentials

Accept

(optional)

Provide the acceptable data type ie: 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" : "28800",

  "token_type" : "Bearer",

  "access_token" : "<ACCESS_TOKEN>",

  "refresh_token" : "<REFRESH_TOKEN>"

  }

Parameter

Description

issued_at

Refers to the UNIX timestamp of our system in central standard time  

expires_in

The number of seconds remaining, from the time it was requested, before the token will expire, applications can use this time to send refresh the token requests

token_type

Refers to the type of token

access_token

The access_token is valid for a limited period described by expires_in seconds.

Currently, the access_token expires in 30 minutes.

refresh_token

The refresh_token can be used to obtain a new access_token.

Currently, the refresh_token expires in 24 hours

 

Step 2: 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 as a 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

curl -v -X GET https://sandbox-us-api.experian.com/business/score/v2/directors

      -H "Accept: application/json" \

      -H "Authorization: Bearer $ACCESS_TOKEN"

 

Step 3: ACCESS TOKEN REFRESH

You may obtain a new access_token, whenever the access_token has expired, by exchanging the refresh_token that is associated with the access_token.

Below is a sample request:

curl -X POST https://sandbox-us-api.experian.com/oauth2/v1/token \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  -H 'grant_type: refresh_token' \
  -H 'refresh_token: $REFRESH_TOKEN' \
  -d '{"username": "<USERNAME>","password": "<PASSWORD>","client_id": "<CLIENT_ID>","client_secret": "<CLIENT_SECRET>"}'

Response

Status code 200

{

  "issued_at" : "1500914612223",

  "expires_in" : "28800",

  "token_type" : "Bearer",

  "access_token" : "$ACCESS TOKEN",

  “refresh_token”: “$REFRESH TOKEN”

}

 

Step 4: TOKEN REVOCATION

If the client chooses to revoke 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:

curl -X POST https://sandbox-us-api.experian.com/oauth2/v1/revokeToken \
  -H 'client_id: GfiivuSKYI8oU5X6QQmAdGrXlNGkp8Ex' \
  -H 'client_secret: XM2qQ4XapHjPEbZ6' \
  -H 'token: eyJraWQiOiJBSmpTMXJQQjdJODBHWjgybmNsSlZPQkF3V3B3ZTVYblNKZUdSZH' \

 

Parameter

Description

client_id

(Required)

client_id associated with the developer app

client_secret

(Required)

client_secret associated with the developer app

token

(Required)

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