Skip to main content

Configure SMS message courier

For sending SMS Ory Kratos uses an external SMS gateway, which must have HTTP API (such as Twilio, your local SMS sender, or your own microservice). Request method, headers, body, and content-type are fully configurable using options below.

Configuration​

Default configuration of Ory Kratos doesn't include sending SMS. To enable it you need to set "enabled" flag to true, sender URL, authorization (if needed) and request body format.

Sender phone number​

SMS message will come to the recipient from this phone number. Depending on your SMS sender settings you can use letters here (for example "Your Org Name"). Default value is equal to "Ory Kratos".

path/to/my/kratos/config.yml
# kratos -c path/to/my/kratos/config.yml serve
courier:
  sms:
    from: "+12065550110"

Request configuration​

path/to/my/kratos/config.yml
# kratos -c path/to/my/kratos/config.yml serve
courier:
  sms:
    request_config:
      url: https://api.twilio.com/2010-04-01/Accounts/YourAccountID/Messages.json
      method: POST
      body: file://./path/to/path/to/my/kratos/config/twilio.request.jsonnet
      header:
        "Content-Type": "application/x-www-form-urlencoded"
      auth:
        type: basic_auth
        config:
          user: YourUsername
          password: YourPass

The configuration consists of:

  • url - the URL, which should be called (mandatory). It needs to be absolute, start with http:// or https:// scheme, and include path part - for example "https://api.sender.com/v1/message".
  • method - the HTTP method (GET, POST, ...) (mandatory)
  • body - URI of a JsonNet template, used to render the payload to send (optional). Use a file://path/to/body.jsonnet URL for referring to local files. This property is ignored for HTTP methods, which don't support sending of HTTP body payloads (TRACE).
  • auth - configuration of authentication and authorization mechanisms to be used by request

Courier binds the from, to, and body variables into the JsonNet template. These variables are available through a ctx object. For example to create a body looking like { to: "<some-number>" } to be sent to the SMS provider endpoint, the jsonnet template would look like this:

function(ctx) {
  from: ctx.from,
  to: ctx.to,
  body: ctx.body
}

Authentication and Authorization​

For auth following mechanisms are supported:

  • Authentication via an Api Key. Type must be set to api_key.
  • Authentication via Basic Authentication. Type must be set to basic_auth.

For api_key the config looks as follows:

name: Some-Name
value: The-Value-of-My-Key
in: header # alternatively cookie

All properties are mandatory.

For basic_auth the config looks as follows:

user: My-User
password: My-Pass-Value

All properties are mandatory.