Legacy Authentication

For all new integrations, use Token Authentication. It works with every API. Legacy authentication methods are supported only for backwards compatibility and should not be used for new implementations.

OAuth

OAuth exists in two major versions: OAuth 1.0 and OAuth 2.0, which are not compatible with each other. GatewayAPI supports OAuth 1.0a for legacy integrations.

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

The HTTP Basic authentication scheme is another method supported for backwards compatibility with older integrations.

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 an 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}]}

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.

Credentials

Basic authentication can be used with legacy credentials (username and password).

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.

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 an HTTP request being redirected to HTTPS can risk leaking the token.