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
sender_id	YOUR BRAND	Optional field to pass the sender (phone number, short code, brand name) of the text message.

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 compose your own message.

API

POST /send-sms 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",
  "sender_id": "YOUR BRAND"
}

Successful response

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