All requests to the API’s of WebApiServices are protected by SSL, are only available using the HTTPS protocol and require you to be authenticated. Protocols other then HTTPS and un-authenticated requests to the API’s of WebAPIServices are refused.

Authentication

Authentication is handled by the Xploration Authentication Service, which is a collection of centralized authentication and authorization endpoints for initiating and managing secure interaction with the API’s of WebApiServices. This authentication API implements the flows and grants associated with the OpenID Connect protocol.

Client Setup

To be able to use the WebApiServices API’s you need an active account.
If you don’t have an account yet, you may register one at https://auth.xploration.nl/register.
After an account is registered and an API subscription is activated on your account, you will be able to authenticate and use the API’s.

Discovery Document

The Xploration Authentication Service exposes a number of endpoints for authentication, requesting tokens, public keys and other configuration information. Since the Xploration Authentication Service is an OpenId Connect service, you will be able to retrieve a discovery document, which contains all the information about those authentication endpoints. The discovery document is available at https://auth.xploration.nl/.well-known/openid-configuration.

 

Getting Authenticated

To be able to use the WebApiServices API’s you must be authenticated and use the obtained access_token with every request.
The OpenId Connect flow used for authentication for machine to machine is the “Client Credentials flow”, and is available at https://auth.xploration.nl/connect/token.

Method POST
Headers Accept: application/json
Content-Type: application/x-www-form-urlencoded
Body
Name Description Value Mandatory
grant_type Determines the authentication flow client_credentials
client_id The id of the registered client 342khkhsd$34345sf44df
client_secret The secret of the registered client MySuperComplexSecret
Example
POST https://auth.xploration.nl/connect/token HTTP/1.1
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Host: auth.xploration.nl
Content-Length: 153

grant_type=client_credentials&client_id=3457dsf-sdf898345-dfllkr34234-8973efa&client_secret=MySuperComplexSecret
Success Response Code: 200
Description: Returned when the token request was succesfull

{
  "access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6I",
  "expires_in":3600,
  "token_type":"Bearer"
}
Error Reponses Code: 400
Description: Returned when an invalid scope was requested

{"error":"invalid_scope"}

Code: 400
Description: Returned when an grant_type other then the supported grant types was provided

{"error":"unsupported_grant_type"}

Code: 400
Description: Returned when an invalid client_id and/or client_secret is provided

{"error":"invalid_client"}

Api requests

After succesfully obtaining an access_token from the Xploration Authentication Service, requests to the WebApiServices API’s can be made using this access_token in the header of those requests.

Example

Description Retrieves data from MyApi
Url https://myAPI.webapiservices.com/MyData
Method GET
Example request
GET https://myAPI.webapiservices.com/MyData HTTP/1.1
Accept: application/json
Authorization: Bearer MyAccessToken
Success Response Code: 200
Description: The data returned after a succesfull request

[{
  "first_property": "first value",
  "secondproperty": "second value"
}]
Error Responses Code: 403
Description: Returned when an invalid Authorization header was send along with the request