API Authentication

When using our APIs to send messages you need to provide means of authentication so our servers can verify which account the request is made from and thus who is sending the messages.

You can choose either API Token, HTTP Basic Authentication or OAuth. We encourage the use of API Token to most users.

Create an Account

Before you can start using the GatewayAPI service, you will need to register an account with us. When creating an account we create a set of credentials for you to use in your own application - you can of course create new ones via the dashboard.

Token Authorization Header

The simplest form used for authentication is to just set the Authorization header with the token itself using the Token authorization scheme.

The value of the Authorization header is specified to be {scheme} {value}, and thus when using the scheme Token, it becomes Token {value}.

POST /rest/mtsms HTTP/1.1
Host: gatewayapi.com
Authorization: Token your-token-here
Accept: application/json, text/javascript
Content-Type: application/json

{"message": "Hello World", "recipients": [{"msisdn": 4512345678}]}

Token vs Bearer

To anybody familiar with the current landscape of HTTP authentication schemes, this will look very similar to the Bearer scheme, and in fact it is.

But the Bearer scheme has become so intertwined with JWT sessions and OAuth that it is just simpler and avoids a lot of support dialogue to use a differently named scheme when just transporting a simple token.

OAuth

The OAuth specification exists in two versions; 1 and 2, each having little to do with the other. OAuth 1.0a is suitable for API usage without a user present and provides protection against replay attacks.

No user interaction is required for the authentication, so this part is skipped from OAuth. There are only two parties: consumer and service provider. Thus, this is a special two-legged variant of OAuth 1.0a. The signing process is identical to the normal three-legged OAuth, but we simply leave the token and secret as empty strings.

The OAuth parameters can be sent as the OAuth Authorization header or as query string parameters. Your framework should take care of all the details for you, however if you are fiddling with it yourself, it is important that the nonce is unique and the timestamp is correct.

Header example

POST /rest/mtsms HTTP/1.1
Host: gatewayapi.com
Authorization: OAuth oauth_consumer_key="Create-an-API-Key",
  oauth_nonce="128817750813820944501450124113",
  oauth_timestamp="1450124113",
  oauth_version="1.0",
  oauth_signature_method="HMAC-SHA1",
  oauth_signature="t9w86dddubh4XofnnPgH%2BY6v5TU%3D"
Accept: application/json, text/javascript
Content-Type: application/json

{"message": "Hello World", "recipients": [{"msisdn": 4512345678}]}

URL Params example

POST /rest/mtsms?oauth_consumer_key=CreateAKey&oauth_nonce=12345&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1191242096&oauth_version=1.0 HTTP/1.1
Host: gatewayapi.com
Accept: application/json, text/javascript
Content-Type: application/json

{"message": "Hello World", "recipients": [{"msisdn": 4512345678}]}

Basic Authorization Header

In addition to the token authorization header scheme above, it is also possible to authenticate via the Basic scheme.

As specified, the header value must be in the format Basic {value} where the value this time is a base64 encoded string containing username and password.

Many HTTP clients today support a shorthand for building and setting the header correctly when provided with values for username and password. And we would recommend using those instead of building the string manually and base64 encode it.

However, if you must build this yourself, the username+password value that needs to be base64 encoded must have this format {username}:{password}, neither fields are optional, and the colon must be included.

In the end it should be possible to make a HTTP request that looks something like this:

POST /rest/mtsms HTTP/1.1
Host: gatewayapi.com
Authorization: Basic Zm9vOmJhcg==
Accept: application/json, text/javascript
Content-Type: application/json

{"message": "Hello World", "recipients": [{"msisdn": 4512345678}]}

Token

You can use Basic Auth with our API tokens, these are created and found under “API”, “API Keys” on our dashboard

Since the Basic scheme requires a username and a password, fitting the token in this is a little unconventional: use the token as the username and an empty string as the password.

Credentials

You can use Basic Auth with credentials (deprecated: i.e. username + password), or with an API Token. The API Token is sent as the username with the password left empty. You can find and create a set of credentials under “API”, “Credentials (deprecated)” on our dashboard.

Setting the fields should be relatively simple as the credential field labeled “Username” should be used for the username and the credential field labeled Password should be used in the password field.

Query String and Form

If it is not possible to specify an Authorization header, it is possible to pass authorization with values submitted via the query string or form element of the HTTP request. This is mostly used for compatibility with older legacy systems, designed back when security was less of a concern.

Token

One option is to use a token as described above, sent as token:

POST /rest/mtsms?token=your-token HTTP/1.1
Host: gatewayapi.com
Accept: application/json, text/javascript
Content-Type: application/json

{"message": "Hello World", "recipients": [{"msisdn": 4512345678}]}

Credentials

It is also possible to use our credentials of username and password. The username is sent as user, and the password as password.

POST /rest/mtsms?user=your-username&password=your-password HTTP/1.1
Host: gatewayapi.com
Accept: application/json, text/javascript
Content-Type: application/json

{"message": "Hello World", "recipients": [{"msisdn": 4512345678}]}

Security Considerations

We can, however, only recommend this when no other options are possible and even then only half-heartedly. Sending the authentication token via the query string will most likely result it being logged proxy servers between the client and the server - increasing the risk of leaking the token.

We strongly encourage checking that any clients using query string authentication makes requests directly to HTTPS, as even a HTTP request being redirected to HTTPS can risk leaking the token.