Skip to content

Dangerous Goods API

Authentication

OAuth2 access tokens issued with the client credentials grant, an alternative to HTTP Basic authentication for every authenticated operation

Issue an OAuth2 access token

Issues an OAuth2 access token using the client_credentials grant (RFC 6749 section 4.4).

The client credentials are the same ones used for HTTP Basic: client_id is the API user name and client_secret is that user's password. They may be supplied either in the request body or in an Authorization: Basic header, as permitted by RFC 6749 section 2.3.1, but not both at the same time.

The request body must be application/x-www-form-urlencoded and must contain grant_type=client_credentials. The optional scope parameter is accepted and ignored: authority is determined by the roles and licences of the user, not by scopes.

This operation does NOT use the standard response envelope of the rest of the API: both the success body and the error body follow the flat shape defined by RFC 6749 sections 5.1 and 5.2, so that off-the-shelf OAuth2 clients can consume them.

The token is valid for one hour. Clients should cache it and reuse it until shortly before it expires; requesting one token per call would be slower than plain Basic. A password change invalidates every outstanding token of that user. There is no individual token revocation and no refresh token, which RFC 6749 section 4.4.3 explicitly discourages for this grant.

Request Body schema: application/x-www-form-urlencoded
required

Token request, form-urlencoded as required by RFC 6749 section 3.2.

grant_type
required
string

Must be client_credentials.

client_id
string

API user name. Omit when the credentials travel in the Authorization header.

client_secret
string

Password of that API user. Omit when the credentials travel in the Authorization header.

scope
string

Optional. The authority granted to the token is determined by the roles and licences of the user.

Responses

200

Token issued

Response Schema: application/json

access_token
string

The issued opaque access token.

token_type
string

Type of the token, always bearer.

expires_in
integer

Lifetime of the token in seconds.

400

Invalid request or invalid client credentials

Response Schema: application/json

error
string

Error code, as defined by RFC 6749 section 5.2.

error_description
string

Human-readable description of the error. It is deliberately identical for an unknown user and for a wrong secret, so that it cannot be used to enumerate users.

post/oauth2/token
https://emea.dgassistant.com/api/v2/rest/oauth2/token
https://amer.dgassistant.com/api/v2/rest/oauth2/token
https://apac.dgassistant.com/api/v2/rest/oauth2/token

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "bearer",
  • "expires_in": 3599
}
Content type
application/json
{
  • "error": "invalid_client",
  • "error_description": "Client authentication failed."
}