On this page
Custom Templates API
The Okta Templates API provides operations to manage custom Templates.
Note: Only SMS custom Templates are available through the API.
SMS Templates customize the SMS message that is sent to users. One default SMS Template is provided. All custom Templates must have the variable ${code}
as part of the text. The ${code}
variable is replaced with the actual SMS code when the message is sent. Optionally, you can also use the variable ${org.name}
. If a Template contains ${org.name}
, it is replaced with the organization name before the SMS message is sent.
Note: Some of the curl code examples on this page include SSWS API token authentication. However, Okta recommends using scoped OAuth 2.0 and OIDC access tokens to authenticate with Okta management APIs. OAuth 2.0 and OIDC access tokens provide fine-grain control over the bearer's actions on specific endpoints. See Okta API authentication methods.
Get started with custom Templates
Explore the custom Templates API: (opens new window)
Template operations
Add SMS Template
POST /api/v1/templates/sms
Adds a new custom SMS Template to your organization
Request parameters
Parameter | Description | ParamType | DataType | Required |
---|---|---|---|---|
Definition of the new custom SMS Template | Body | SMS Template | TRUE |
Response parameters
The created SMS Template
Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
"name": "Custom",
"type": "SMS_VERIFY_CODE",
"template": "${org.name}: your verification code is ${code}",
"translations": {
"es" : "${org.name}: el código de verificación es ${code}",
"fr" : "${org.name}: votre code de vérification est ${code}",
"it" : "${org.name}: il codice di verifica è ${code}"
}
}' "https://${yourOktaDomain}/api/v1/templates/sms"
Response example
{
"id": "cstkd89Qu2ypkxNQv0g3",
"name": "Custom",
"type": "SMS_VERIFY_CODE",
"template": "${org.name}: your verification code is ${code}",
"created": "2016-06-23T17:20:22.000Z",
"lastUpdated": "2016-06-23T17:20:22.000Z",
"translations": {
"it": "${org.name}: il codice di verifica è ${code}",
"fr": "${org.name}: votre code de vérification est ${code}",
"es": "${org.name}: el código de verificación es ${code}"
}
}
Get SMS Template
GET /api/v1/templates/sms/${smsTemplateId}
Fetches a specific Template by id
Request parameters
Parameter | Description | ParamType | DataType | Required |
---|---|---|---|---|
smsTemplateId | id of a Template | URL | String | TRUE |
Response parameters
Fetched SMS Template
Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/templates/sms/${templateId}"
Response example
{
"id": "cstkd89Qu2ypkxNQv0g3",
"name": "Custom",
"type": "SMS_VERIFY_CODE",
"template": "${org.name}: your verification code is ${code}",
"created": "2016-06-23T17:20:22.000Z",
"lastUpdated": "2016-06-23T17:20:22.000Z",
"translations": {
"it": "${org.name}: il codice di verifica è ${code}",
"fr": "${org.name}: votre code de vérification est ${code}",
"es": "${org.name}: el código de verificación es ${code}"
}
}
List SMS Templates
GET /api/v1/templates/sms
Enumerates custom SMS Templates in your organization. Optionally, a subset of Templates can be returned that match a Template type.
Request parameters
Parameter | Description | ParamType | DataType | Required | Default |
---|---|---|---|---|---|
templateType | The type of Template that you are searching for. Valid value: SMS_VERIFY_CODE | Query | String | FALSE | N/A |
Note: Search performs an exact match of the type, but this is an implementation detail and may change without notice.
Response parameters
Array of SMS Templates of matching type
Request example
curl -v -X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/templates/sms"
Response example
[
{
"id": "cstkdgSQOUacCuF750g3",
"name": "Custom",
"type": "SMS_VERIFY_CODE",
"template": "${org.name}: your enrollment code is ${code}",
"created": "2016-06-23T17:41:07.000Z",
"lastUpdated": "2016-06-23T17:41:07.000Z",
"translations": {
"it": "${org.name}: il codice di iscrizione è ${code}",
"fr": "${org.name}: votre code d'inscription est ${code}",
"es": "${org.name}: su código de inscripción es ${code}"
}
}
]
Update SMS Template
PUT /api/v1/templates/sms/${smsTemplateId}
Updates the SMS Template
Note: The default SMS Template can't be updated.
Request parameters
Parameter | Description | ParamType | DataType | Required |
---|---|---|---|---|
smsTemplateId | id of the SMS Template to update | URL | String | TRUE |
Full description of the custom SMS Template | Body | SMS Template | TRUE |
Note: All profile properties must be specified when you update an SMS custom Template. Partial updates are described in the Partial SMS Template update section.
Response parameters
Updated SMS Template
Request example
curl -v -X PUT \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
"name": "Custom",
"type": "SMS_ENROLLMENT_CODE",
"template": "${org.name}: your enrollment code is ${code}",
"translations": {
"it": "${org.name}: il codice di iscrizione è ${code}",
"es": "${org.name}: su código de inscripción es ${code}",
"de": "${org.name}: ihre anmeldung code ist ${code}"
}
}' "https://${yourOktaDomain}/api/v1/templates/sms/${templateId}"
Response example
{
"id": "cstkdgSQOUacCuF750g3",
"name": "Custom",
"type": "SMS_ENROLLMENT_CODE",
"template": "${org.name}: your enrollment code is ${code}",
"created": "2016-06-23T17:41:07.000Z",
"lastUpdated": "2016-06-23T17:47:06.000Z"
}
Partial SMS Template update
POST /api/v1/templates/sms/${smsTemplateId}
Updates only some of the SMS Template properties:
- All properties within the custom SMS Template that have values are updated.
- Any translation that doesn't exist is added.
- Any translation with a null or empty value is removed.
- Any translation with non-empty/null value is updated.
Note: The default SMS Template can't be updated.
Request parameters
Parameter | Description | ParamType | DataType | Required |
---|---|---|---|---|
smsTemplateId | id of the SMS Template to update | URL | String | TRUE |
Attributes that we want to change | Body | SMS Template | TRUE |
Note: A full SMS Template update is described in the Update SMS Template section.
Response parameters
Updated SMS Template
Request example
curl -v -X POST \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
-d '{
"translations": {
"de" : "${org.name}: ihre bestätigungscode ist ${code}."
}
}' "https://{yourOktaDomain}/api/v1/templates/sms/${templateId}"
Response example
{
"id": "cstkd89Qu2ypkxNQv0g3",
"name": "Custom",
"type": "SMS_VERIFY_CODE",
"template": "${org.name}: your verification code is ${code}",
"created": "2016-06-23T17:20:22.000Z",
"lastUpdated": "2016-06-23T17:58:10.000Z",
"translations": {
"de": "${org.name}: ihre bestätigungscode ist ${code}.",
"it": "${org.name}: il codice di verifica è ${code}",
"fr": "${org.name}: votre code de vérification est ${code}",
"es": "${org.name}: el código de verificación es ${code}"
}
}
Remove SMS Template
DELETE /api/v1/templates/sms/${smsTemplateId}
Removes an SMS Template
Note: The default SMS Template can't be removed.
Request parameters
Parameter | Description | ParamType | DataType | Required |
---|---|---|---|---|
smsTemplateId | id of the SMS Template to delete | URL | String | TRUE |
Response parameters
There is no content in the response.
Request example
curl -v -X DELETE \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: SSWS ${api_token}" \
"https://${yourOktaDomain}/api/v1/templates/sms/${templateId}"
Response example
HTTP/1.1 204 No Content
SMS Template object
Example
{
"id": "cstk2flOtuCMDJK4b0g3",
"name": "Custom",
"type": "SMS_VERIFY_CODE",
"template": "Your ${org.name} code is: ${code}",
"created": "2016-06-21T20:49:52.000Z",
"lastUpdated": "2016-06-21T20:49:52.000Z",
"translations": {
"it": "Il codice ${org.name} è: ${code}.",
"fr": "Votre code ${org.name}: ${code}.",
"es": "Tu código de ${org.name} es: ${code}."
}
}
SMS Template attributes
All Templates have the following properties:
Property | Description | DataType | Readonly | MinLength | MaxLength |
---|---|---|---|---|---|
id | Unique key for the Template | String | TRUE | 20 | 20 |
name | Human-readable name of the Template | String | FALSE | 1 | 50 |
type | Type of the Template | String | FALSE | 1 | 50 |
template | Text of the Template, including any macros. | String (See note below) | FALSE | 1 | 161 |
created | Timestamp when the Template was created | String (ISO-8601) | TRUE | N/A | N/A |
lastUpdated | Timestamp when the Template was last updated | String (ISO-8601) | TRUE | N/A | N/A |
translations | A key/value map of translations | Translations object | N/A | N/A | N/A |
Note: The length of your SMS message can't exceed 160 characters. If the verification code portion of the message falls outside of the 160-character limit, your message isn't sent.
Translation attributes
Template translations are optionally provided when you want to localize the SMS messages. Translations are provided as an object that contains key:value
pairs: the language and the translated Template text.
"translations": {
"it": "Il codice ${org.name} è: ${code}.",
"fr": "Votre code ${org.name}: ${code}.",
"es": "Tu código de ${org.name} es: ${code}."
}
The key portion is a two-letter country code that conforms to ISO 639-1 (opens new window), and the value is the translated SMS Template.
Note: Just like with regular SMS Templates, the length of the SMS message can't exceed 160 characters.
SMS Template types
Type | Description |
---|---|
SMS_VERIFY_CODE | This Template is used when the SMS for code verification is sent. |
SMS Template macros
Only two macros are supported for SMS Templates:
Type | Description |
---|---|
${code} | The one-time verification code that is required for sign in. |
${org.name} | The name of the Okta organization that the user is trying to authenticate into. |