The SMS subsystem in the Curity Identity Server can be configured to use the REST client. This is a generic client that expects a HTTP backend server that follows a small protocol defined in this section.

It is meant as a convenient extension point when an organization wants to support an SMS provider not supported by default in Curity Identity Server.

Sending a message

When the server needs to send an SMS it will issue a POST to the defined endpoint in the configuration.

The message has the following format:

Listing 197 Sending an SMS
  "to" : "+4612345678",
  "message" : "Hello World"

The to number will be in the format enforced by the data stores that contain the number. Curity will not add additional restrictions to this number unless validation procedures are used when the user adds the number.

Response and Errors


On success the backend is expected to return a 200 with no body.


On failure due to invalid input such as an invalid phone number or invalid message a 400 should be returned with one of the following error code as message body:

  "error" : "invalid-phonenumber"

On all other failures a 500 is expected from the backend service. A 500 from the backend, will result in an Internal Server Error page for the user, which is a severe error. A body can be returned with an error tag which will be written in the server log as a WARN statement.


Authentication is governed by the HTTP client used to establish connections.

For details, see Http Clients and http client configuration.