16.1.1.27. SMS Gateway endpoints

The SMS-gateway REST API manages SMS gateway definitions used to send SMS messages (for SMS-token OTP delivery, notifications, and event handlers). See SMS Gateway configuration for the conceptual chapter covering the supported provider modules and their options.

All endpoints require admin authentication. Read access is gated by the admin policy action smsgateway_read; create, update and delete are gated by smsgateway_write.

GET /smsgateway/(gwid)
GET /smsgateway/

Return SMS gateway information. The behavior depends on the path:

  • /smsgateway/ — return all configured gateway definitions as a list of dictionaries.

  • /smsgateway/<gwid> — return the gateway with the given numeric id (still wrapped in a single-element list).

  • /smsgateway/providers — return a dictionary keyed by provider class name, where each value describes the configuration parameters the class accepts. This special path is used by the WebUI to render the gateway-creation form; it does not look up a gateway with the literal id providers.

Requires admin authentication and the policy action smsgateway_read.

Parameters:

  • gwid – optional path component, the numeric id of a gateway, or the literal string providers for the schema lookup.

Status Codes:

  • 200 OK – list of gateway dictionaries, or a dictionary of provider schemas, in result.value.

POST /smsgateway

Create or update an SMS gateway definition. If a definition with the given name already exists it is updated; otherwise it is created.

Requires admin authentication and the policy action smsgateway_write.

JSON Parameters:

  • name – unique identifier for the gateway (required).

  • module – dotted Python path of the SMS provider class to use (required, e.g. privacyidea.lib.smsprovider.HttpSMSProvider.HttpSMSProvider).

  • description – free-form description.

  • option.* – provider-specific options. Field names are taken after the option. prefix (e.g. option.URL becomes the URL option).

  • header.* – HTTP headers to send with provider requests, same naming scheme as option.*.

Status Codes:

  • 200 OK – database id of the gateway in result.value.

DELETE /smsgateway/(identifier)

Delete the SMS gateway definition with the given identifier and all its options and headers.

Requires admin authentication and the policy action smsgateway_write.

Parameters:

  • identifier – path component, the gateway name.

Status Codes:

  • 200 OK – number of deleted rows in result.value (0 if no gateway with that name existed).

DELETE /smsgateway/option/(gwid)/(key)

Delete a single option (or header) from an SMS gateway definition.

Requires admin authentication and the policy action smsgateway_write.

Parameters:

  • gwid – path component, the numeric id of the gateway.

  • key – path component, the option name to delete. Prefix with header. to remove a header instead of an option (e.g. pass header.X-Foo to delete the X-Foo header).

Status Codes:

  • 200 OK – number of deleted rows in result.value.