Authentication Process

Implementation of D&B Direct API services using REST methodology involves obtaining an Authentication Token, that is then submitted with subsequent requests during a particular session (up to 24 hours).

NOTE: See Token Management section for more details.

Secure access to D&B Direct services is managed through the use of an Authentication Token, which can be obtained by sending an HTTP POST request to Authentication Service URL, passing a valid username and password in the HTTP header. The 2.0 services do not require that an API key be supplied. If the user credentials are valid, an Authentication Token (valid for 24 hours) will be returned back in the Authorization tag in the HTTP header of the response.

Once an Authentication Token is obtained, it should be embedded in the HTTP header of all subsequent requests. If the Authentication Token is valid and the user is entitled to access the product or feature being requested, the service will be processed and requested information returned as a JSON object. If the Authentication Token is invalid, an error response will be returned. The security related response codes are prefixed with "SC."

In a multi-server configuration, a single token may be shared among a customers' servers and/or each server may obtain and use a unique token concurrently with other servers using different tokens. Regardless of the token usage, the Queries Per Second (QPS) is enforced as a single measure across all customer requests.

Sample Request - Get New Token

POST https://direct.dnb.com/Authentication/V2.0/
x-dnb-user: MyUsername
x-dnb-pwd: MyPassword

[BODY]
TransactionDetail: {
   "ApplicationTransactionID": "{user-defined}",
   "ServiceTransactionID": "{user-defined}",
   "TransactionTimestamp": "2001-12-17T09:30:47Z"
}

A {version} parameter is NOW required when initiating a request to the Authentication service.

Response - Success

HTTP/1.1 200 OK
Authorization: <MyToken>
Date: Wed, 09 Oct 2013 18:47:22 GMT

[BODY]
{							
	TransactionDetail: {						
		ApplicationTransactionID: "{user-defined}",					
		ServiceTransactionID: "{user-defined}",					
		TransactionTimestamp: "2001-12-17T09:30:47Z"					
	},						
	TransactionResult: {						
		ResultID: "CM000",					
		ResultText: "Success",					
		ResultMessage: {					
			ResultDescription: "Success"				
		}					
	},						
	AuthenticationDetail: {						
		Token: "<MyToken>"					
	}						
}							

Response - Failed

HTTP/1.1 401 ERROR
Authorization: INVALID CREDENTIALS
Date: Wed, 09 Oct 2013 18:51:11 GMT

[BODY]
{
	"TransactionDetail": {
		"ApplicationTransactionID": "{user-defined}",
		"ServiceTransactionID": "{user-defined}",
		"TransactionTimestamp": "2001-12-17T09:30:47Z"
	},
	"TransactionResult": {
		"SeverityText": "Fatal",
		"ResultID": "SC001",
		"ResultText": "Your user credentials are invalid. Please contact your D&B Representative or your local Customer Service Center.",
		"ResultMessage": {
			"ResultDescription": "Invalid user credentials. Please contact your D&B Representative or your local Customer Service Center."
		}
	}
}

Sample Request - Invoke Operation with Token

GET https://direct.dnb.com/V4.0/organizations?CountryISOAlpha2Code=US&SubjectName=GORMAN%20MANUFACTURING&match=true&MatchTypeText=Advanced&TerritoryName=CA
Authorization: <MyToken>

Response - Expired Authentication Token

HTTP/1.1 401 UNAUTHORIZED
Date: Thu, 10 Oct 2013 14:55:19 GMT
Authorization: <MyToken>
Content-Type: application/json
Content-Encoding: gzip

{"MatchResponse": {
  "TransactionDetail":   {
    "ApplicationTransactionID": "REST",
    "ServiceTransactionID": "Id-c04bbdff5256bfd70a7b742e",
    "TransactionTimestamp": "2013-10-10T10:55:19"
  },
  "TransactionResult":   {
    "SeverityText": "Error",
    "ResultID": "SC001",
    "ResultText": "Your user credentials are invalid. Please contact your D&B Representative or your local Customer Service Center."
  }
}}

Password Management

It is the customer's responsibility to treat their credentials as confidential and ensure that access is limited to personnel who develop the applications that will integrate D&B data. Password expiration, forced change and/or lockout rules are not implemented as part of this API.

After three (3) failed authentication attempts, the customer's account will be locked, and subsequent requests will return an SC001 response code. Please contact D&B Customer Support to have the account unlocked.

Customers who would like to change the password associated with a specific API username should contact D&B Customer Support. Note, changes to passwords will go into effect immediately. An industry standard hashing algorithm is used for encryption and storage of passwords.

Token Management

Generally, once an Authentication Token is obtained, the same token should be used for all subsequent requests for the next 24 hours, after which, a new token should be generated using the Authentication Service. Various scenarios may invalidate a generated token before the 24 hour period, such as, release updates, disaster recovery, or contract expiration. Please use the following information for taking further action based on response codes returned from services.

• © Dun & Bradstreet, Inc. 2019 – 2024. All rights reserved.