Skip to content

API Authentication

When using our APIs to send messages you need to proved means of authentication so our servers can verify which account the request is made for 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.

API Token

Your API keys are expressed as a key+secret combo, and as an API token. The key+secret is used for oauth while the token can be used for a simpler scheme with better compatibility.

You can send the token as the username via HTTP Basic Authentication, or you may send the token as a query argument or form value. This means that if you can send a HTTP request, you can use Token Authentication.

Examples of requests with the API Token in different locations:

1
2
3
4
5
6
7
POST /rest/mtsms HTTP/1.1
Host: gatewayapi.com
Authorization: Basic R28tQ3JlYXRlLWFuLUFQSS10b2tlbjoK
Accept: application/json, text/javascript
Content-Type: application/json

{"message": "Hello World", "recipients": [{"msisdn": 4512345678}]}
1
2
3
4
5
6
POST /rest/mtsms?token=Go-Create-an-API-token HTTP/1.1
Host: gatewayapi.com
Accept: application/json, text/javascript
Content-Type: application/json

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

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 URL params. 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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
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

1
2
3
4
5
6
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}]}

HTTP Basic Auth

HTTP Basic auth must only be used with HTTPS connections (SSL encrypted), since the credentials are sent as base64 encoded plaintext.

Support is built-in on most networking frameworks, but it is also simple to do yourself. The credentials are sent as a the Authorization header with the value Basic <basic-cookie>.

Basic-cookie is {username}:{password} which is then base64 encoded.

You can use basic auth with credentials (deprecated: ie. username + password), or with an API Token. The API Token is sent as the username with password left empty. You can find and create a set of credentials under “Settings”, “Credentials (deprecated)”, the API Token is available under API Keys.

1
2
3
4
5
6
7
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}]}

If you cannot use/specify an Authorization header, you can provide the username and password as form or query arguments. The username is sent as user, and the password as password.