OAuth2 Authentication

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.

References to APIs using OAuth2