OAuth2 Authentication

OAuth2 Authentication

Sign up for a free trial account

To implement any AfriGIS web services protected by OAuth2, sign up for a free trial account by contacting [email protected]. Assistance is available from the 24-hour Call Centre, should it be required.

Three ‘random’ strings, for each API to be accessed, will be provided: an App Client ID and App Client Secret as well as an API Key.  These will be explained in more detail below.

OAuth2 process

APIs are now deployed to a cloud provider and make use of OAuth2 for authentication and authorisation.  There is a 2-step process to follow:

  1. Obtain an access token that is valid for 1 hour
  2. Call the API with this access token and an API key

 

Obtain an OAuth2 access token

Make a POST request to https://auth.afrigis.services/oauth2/token in Client Credentials mode.

Use Basic Authentication, with the App Client ID as the username and the App Client Secret as the password.

Set the Content-Type to application/x-www-form-urlencoded with a single parameter grant_type set to client_credentials.

The response will be JSON, from which the access_token can be extracted, as in the example below:

{
    “access_token”: “eyJraWQiOiJXcURTMHRaZ2lQb1wvZnVVWVhnaEVYK21USXRLN25oOFBtT0U1eWw2Zmk4Zz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI3dmJsbXZsNm11OWxnc29vcTJhZnB1YjlzcyIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoicGxhY2VzXC9nZW9jb2RlLXJlYWQgcGxhY2VzXC9yZXZlcnNlZ2VvY29kZS1yZWFkIHBsYWNlc1wvYXV0b2NvbXBsZXRlLXJlYWQgcGxhY2VzXC9kZXRhaWxzLXJlYWQiLCJhdXRoX3RpbWUiOjE2MjM2NTkxMDcsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC5ldS13ZXN0LTEuYW1hem9uYXdzLmNvbVwvZXUtd2VzdC0xX1ZlbnJsRjBsQyIsImV4cCI6MTYyMzY2MjcwNywiaWF0IjoxNjIzNjU5MTA3LCJ2ZXJzaW9uIjoyLCJqdGkiOiIyY2ZkMjhjMy1mYTdkLTRhYWEtODY3My0wNzYxZmQ4ZWI5MzUiLCJjbGllbnRfaWQiOiI3dmJsbXZsNm11OWxnc29vcTJhZnB1YjlzcyJ9.PBTrcx6EJ4JHQKzoXQeEMbymT-a4IXuB5hImsxyl284rU_VTb2ryIuE9VQWzBDQjhxkWXUEmntGQaHMre9xyjeDNb4xPsRVE8FyugdFOmJqcXh0W69kLjk44qbLI0CPGRQmTd0w6NhISDhUJzmJHZMNzNn5aA0rrhSfW2fqxZHPKEcWzAy3_USbh7ExOrC1cfmMv6xPXf1xL-b0BKlEcF4AWAYoaT7-v9rWUJ3ZLBQv4IEsQMj-HBZnPX3jk8gAk8ozHoU735yBxWfRAuInUd5UnqIq7xD13koC3tqSTAJz9lS4uEV7wNZXRrGsSTyH9ekVUrXcNb-FrlsuIX5mjRw”,
    “expires_in”: 3600,
    “token_type”: “Bearer”
}

Note that the access_token expires after 3600 seconds i.e., 1 hour, after which your application must renew the token.

Call the API

Now make a GET, POST or other request to the provided endpoint, starting with https://afrigis.services/
The value of the access_token (starting with eyJ…, ending with …jRw in the example above) should be placed in the Authorization HTTP header, along with a prefix of  “Bearer ” (the word Bearer followed by a space then the access_token) i.e.
Authorization: Bearer eyJ…..jRw
Add another HTTP header: x-api-key with the API Key provided by AfriGIS.

 

Error messages

There are some common error messages that might be encountered when accessing the AfriGIS services.

{
    “message”: “The incoming token has expired”
}

Most will be self-explanatory like the one above, but if one similar to the below is encountered:

<access_token> not a valid key=value pair (missing equal-sign) in Authorization header: ‘Bearer <access_token>

 

then double check that the API path after the Base URL is 100% correct, e.g.:

https://afrigis.services/geocode/<incorrect_path_here>/api/v3/address

Exceptions to OAuth2 Authentication: AfriGIS Data and Maps

Lastly, there are a few exceptions to the AfriGIS OAuth2 authentication.   to AfriGIS data and mapping products. These products follow slightly different authentication methods.  Follow the link below for their documentation.