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 |
|
||||||||||||||||
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: {"error":"unsupported_grant_type"} Code: {"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 |