Authentication

Authentication using OAuth2

Our APIs use OAuth2, with the Client Credential flow, for authentication. For general information about OAuth2, see oauth.net. To get access to APIs you first need to create an API Client. For APIs that support Self Service, you can create your own clients in portal.bisnode.com, or get in touch with our support for assistance. For APIs that do not support Self Service e.g. Risk Decisioning, we suggest that you get in touch with our support for assistance. Each client has its own set of credentials; a client id and a client secret. Note that you will only be able to see the client secret at the time it's generated. If you don't retrieve it at that point, you will need to generate a new secret, as we cannot retrieve the clear text value.

Once you have a client with credentials, you can proceed to request an Access Token. When you request an Access Token you provide your credentials and also one or more scopes that the token should be valid for. Which scope to request depends on which APIs you intend to call. Please refer to the individual API documentation to find the scope required.

The Access Token must then be passed in the Authorization header to all subsequent API requests. Note that there is an expiry time for tokens, and you will have to request a new one once it has expired.

For easy access we have provided you with a postman collection.

The instructions below explains the steps in more details.

Get and Use the Access Token

To get an access token you need to make a POST request to the Token Endpoint of the environment you want to access, and provide the client credentials as well as the requested scope for the token.


Environment	Method	Token Endpoint
Sandbox	POST	https://login.bisnode.com/sandbox/v1/token.oauth2
Production	POST	https://login.bisnode.com/as/token.oauth2

The following headers and parameters should be used:

Name	Sent as	Value
Content-Type	Header	"application/x-www-form-urlencoded"
Authentication	Header	"Basic " + Base64(<Client Id>:<Client Secret>)
grant_type	Parameter (body)	"client_credentials"
scope	Parameter (body)	<requested scope> (Note: multiples scopes are delimited by spaces)

Example using cURL

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d 'grant_type=client_credentials&scope=<requested scope>' \
     -u "<Client Id>:<Client Secret>" \
     https://login.bisnode.com/as/token.oauth2

Example successful response:

{
  "access_token": "eyJhb....seAtPCCQ",
  "scope": "<token scope>",
  "token_type": "Bearer",
  "expires_in": 3600
}

If there is a problem with the request, a HTTP 401 Unauthorized response is returned. For example:

{
 "error": "invalid_client",
 "error_description": "Bad credentials"
}

Step 2. Use the Access Token

Send your access token with all requests to the API using the HTTP Authorization header:

Name	Sent as	Value
Authorization	Header	"Bearer " + <your access token here>

You should reuse the access token for multiple calls to the API. See the next section on recommended usage.

Example in cURL - search for person

curl -X GET \
     -H "Authorization: Bearer eyJhb...seAtPCCQ" \
     https://api.bisnode.com/consumerintelligence/person/v2/?firstName=Sven&familyName=Svensson&streetAddress=Vasagatan+9&sourceCountry=SE

Reusing the Access Token

After you have fetched an access token you should save it and use it for subsequent calls to the API. There is no limit on the number of calls it can be used for, but it will expire after a certain time.

We recommend that you use the expires_in field to determine when to request a new access token. It specifies the number of seconds the token will be valid for. Because of possible delays in network communication as well as delays between checking the timestamp and transmitting the actual API request, it is a good idea to request a new token a few seconds before it is about to expire. This minimizes the risk of accidentally using an expired token. If an expired token is used, it will result in a HTTP 401 Unauthorized response:

{
 "error": "invalid_token",
 "error_description": "Invalid Token: token not found, expired or invalid"
}

The following pseudo code illustrates how to use the Token Endpoint together with the API.

function make_authorized_api_request():
    token = get_cached_access_token()
    if token == null or is_soon_to_be_expired(token):
        token = get_new_access_token()
        save_to_cache(token)
    make_api_call(token)


function get_new_access_token():
    token = get_token_from_auth_endpoint()
    token.expiration_timestamp = now().add_seconds(token.expires_in)
    return token

function is_soon_to_be_expired(token):
    # Add time margin to avoid token expiring during call
    if now().add_seconds(60) >= token.expiration_timestamp:
        return true
    return false