REST SMS gateway API specification

This section describes the API that the Token Server expects when the REST SMS gateway is used as the SMS gateway.

See the topic guide about SMS Gateways for instructions on enabling this REST service.

The SMS gateway endpoint (which must be specified via a Docker Compose environment variable) must accept POST requests with following json parameters. It can be protected with basic authentication.

Parameter Example Description
phone_number +31667231451 The phone number
message Your verification code is 345356. The SMS message
verification_code 345356 The verification code used to authenticate the user

In case you don't want to use the message specified in the request from the Token Server you can also use the verification_code field to retrieve the verification code and built your own message.

API

POST  HTTP/1.1
Host: some-gateway.com
Content-Type: application/json;charset=UTF-8
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

{
  "phone_number": "+31667231451",
  "message": "Your verification code is 345356.",
  "verification_code": "345356"
}

Successful response

If the message was send with success the 204 No Content response must be returned. If another response is returned to the Token Server it will interpret this as a failed attempt to send an SMS. In case of an error the Token Server will log the response details (status, reason and body).