API Endpoint

In order to use the APIs of the MessageBird Connectivity Platform, you need to have an account and log in to the Dashboard of the Connectivity Platform.

Authentication

MessageBird's APIs use API keys to authenticate requests. You can create, retrieve, and manage your API keys in your MessageBird Dashboard.

Test API keys have the prefix test_ and live API keys don't require a prefix.

With each API call, you will need to set request headers including your access key to authenticate yourself.

Your API keys carry significant privileges. Please ensure to keep them 100% secure and be sure to not share your secret API keys in areas that are publicly accessible like GitHub. See API Access Key Security for more information.

API Access Key Security

Given your API access key is your authentication token for using MessageBird's APIs, they need to be appropriately secured. One of the easiest ways to think of this is to treat your API access keys just like you would your passwords, including storing them securely and never sharing them with anyone.

One of the most common mistakes that is made with API keys is to inadvertently check them into public repositories on platforms such as GitHub. From here, fraudsters can find and steal your API access key and then use it to send Spam messages and also drain your account balance. There are numerous techniques to avoid this, however storing your API access key in an environment variable, passing them as command line arguments or using a secrets manager can all help to prevent this from occurring. The main takeaway is don't hard-code your API access key and don't check it into a public code repository.

In a similar manner, sharing code snippets on platforms such as PasteBin, GitHub Gists or StackOverflow can inadvertently leak your API access key so ensure that you and your developers are aware of this risk.

MessageBird also takes measures on our side to help detect and mitigate compromised API access keys, however prevention is the best medicine so please ensure you protect your API access keys.

API Errors

MessageBird uses standard HTTP status codes to indicate the success or failure of an API request. Generally speaking, codes in the 2xx range indicate that a request was successfully processed and codes in the 4xx range indicate that there was an error that resulted from the information provided (e.g., authentication, no balance or a missing or wrong parameter).

In case of an error, the body of the response includes a json formatted response that tells you exactly what is wrong.

Error handling

The error object will give you information about the error makes it easier to fix.

Requests

POST and PUT requests to the API should contain a JSON-formatted payload in the request body. Alternatively, resource attributes can be sent through GET parameters.

HTTP Methods

The MessageBird API uses HTTP verbs to understand if you want to read (GET), delete (DELETE), or create (POST) an object. When your website or application doesn't have the possibility to do a POST or DELETE, we provide the ability to set the method through the query parameter _method.

Alternatively, resource attributes can be sent through GET attributes instead of a JSON body.

Verifying HTTP requests

We sign our HTTP requests to allow you to verify that they actually came from us (authentication) and that they haven't been altered along the way (integrity).

Please keep in mind that the rundown below applies to all our services apart from our Voice Calling API Dynamic Call Flows, where the signature validation process is slightly different.

You can conduct a live test via Flow Builder. Please do not use the "Test" Flow Simulator as it does not invoke an HTTP Request to your endpoint.

What is request signing?

For each HTTP request that MessageBird sends, a MessageBird-Signature-JWT header is added.

The MessageBird-Signature-JWT header is a signature that consists of all the information that is required to verify the integrity of the request. The signature is generated from the request URL and request body and is signed with the HMAC-SHA256 algorithm using your your signing key. You can validate this signature using our SDKs (see signature usage) to ensure that the request is valid and unaltered. The token also includes timestamp claims that allow you to prove the time of the request, protecting from replay attacks and the like. Easy!

What if my signing secret has been compromised?

If your secret has been leaked, don't panic. You can easily regenerate your secret at any time via your MessageBird Dashboard by clicking on the 'Regenerate' blue button.

Signature details

The MessageBird-Signature-JWT header is a JWT token consisting of three sections: header, payload, and signature.

• Header:
  • typ - is the type of the token, which is always JWT.
  • alg - is the algorithm that the token is signed with, HS256 reprensents HMAC-SHA256 algorithm.
• Payload (claims):
  • iss - is the issuer of the token, which is always MessageBird.
  • nbf - is the UNIX timestamp in seconds, after which the token becomes valid.
  • exp - is the UNIX timestamp in seconds, after which the token becomes invalid.
  • jti - is a unique ID that you can use to detect replay attacks.
  • url_hash - is a hex-encoded SHA256 hash of the canonicalized URL that the webhook was sent to.
  • payload_hash - is a hex-encoded SHA256 hash of the payload of the HTTP body.
• Signature

When handling the token without the help of our SDKs, make sure you always validate the header alg as HS256 and all the above claims. If either the url_hash or payload_hash claim checks are skipped, no query parameters or request body should be trusted.

Signature usage