Authentication

Requests made to our APIs must be authenticated, there are two ways to do this:

  1. Authenticating using your API Key and username
  2. Authenticating using an Auth Token

Authenticating using your API Key and username

Your username

When working with the sandbox (our development environment), the username is always sandbox.

When in the live environment, this is the specific username of the application making the request. Here is an article from the help center on how to make a production application.

Your API Key

You can generate an API key from the dashboard, here is an article from the help center on how to generate an API Key.

When a new API key is generated, you can no longer use the old one. After you generate your API key, we strongly advise that you copy it and keep it somewhere safe. It will not be displayed again because Africa's Talking does not log or save your API Key for security reasons. If you lose it, you'll have to generate a new one.

Making an API call

You need to include the API key in the request header as a field called apiKey.

The place where the username should be included depends on the type of request.

For GET requests e.g. fetch messages, the username should be passed as a query parameter.

For POST requests in which parameters are sent as a url encoded form e.g. in sending SMS, then the username should be included as one of the parameters within the form.

For POST requests that require JSON in the request body e.g. in mobile checkout, then the username should be included in the JSON sent in the body of the request.

Authenticating with an Auth Tokens

For instances where it may not be possible to include your APIKey in your application such as in a mobile application, we provide a way to authenticate using temporary auth tokens.

Getting the Token

To generate the auth token, make a POST request to https://api.africastalking.com/auth-token/generate with your username and API Key. This request should be made from your server as you should not inclue your apiKey in client code.

You will receive a response like this:

{
    "token": "ATtkn_abcdefghijklmnopqrstuvwxyz",
    "lifetimeInSeconds": 3600
}

You will be able to use that token to make API calls. The token will be valid for value of lifetimeInSeconds and you should generate a new token before it expires.

You need to include the Auth Token in the request header as a field called authToken. The place where the username should be included depends on the type of request you're making.