Custom Telephony Provider

The Custom Telephony Provider API provides operations to manage your custom telephony providers and their credentials. Creating a custom telephony provider enables you to use the Phone authenticator. See Use your own telephony provider to learn more about using your own telephony provider.

To create a custom telephony provider, you must first create an account with a supported telephony provider. After you have an account, you can use this API to add and then manage your provider credentials. Twilio and Telesign are the only supported telephony providers at this time.

List all custom telephony providers
Early AccessIdentity Engine
OAuth 2.0 scope:
  • okta.customTelephonyProvider.read

Lists all custom telephony providers that are configured in your org

Responses
200

OK

403

Forbidden

404

Not Found

get/api/v1/telephony-providers
Request samples 
Response samples 
application/json
[
  • {
    • "id": "oct3v00k4iOFlEJmQ806",
    • "isPrimaryProvider": true,
    • "enabled": true,
    • "providerCapability": "ALL",
    • "providerName": "TWILIO",
    • "providerSid": "ACb49fb19a09b2f5d2f121fe1c207689dt",
    • "providerSettings": {
      }
    },
  • {
    • "id": "oct3v00k4iOFlEG3dR45",
    • "isPrimaryProvider": false,
    • "enabled": true,
    • "providerCapability": "ALL",
    • "providerName": "TELESIGN",
    • "providerSid": "AC42tfy19a09b2f5d2f121fe1c207fg456r",
    • "providerSettings": {
      }
    }
]
Create a custom telephony provider
Early AccessIdentity Engine
OAuth 2.0 scope: 
  • okta.customTelephonyProvider.manage
Creates a custom telephony provider with the provided credentials


Request 
Request Body schema: application/json
required
providerAuthToken
string
The authentication token that's used to authenticate requests to the telephony provider. Your telephony provider gives you this token.


 
providerCapability
string
The types of telephony operations (SMS or Voice) that you use with your telephony provider.


ALL is the only valid value. It indicates that your provider can handle both SMS messages and voice calls. You're not required to use both types of telephony operations, but your provider can support both.


 Value: "ALL"  
providerName
string
The name of the telephony provider


 Enum: "TWILIO" "TELESIGN"  
object (CustomTelephonyProviderSettings) 
Settings for custom telephony provider.


These settings vary based on the telephony provider and the type of telephony operation (SMS or Voice). For sms and call, you can select one method per telephony operation (sms and call) for sending messages or voice calls.




Note: Configure your telephony provider settings before selecting the methods for sending SMS messages or making voice calls. For example, if you select Twilio as your telephony provider, and you want to send SMS messages using Twilio's Verify Service, ensure that you have the Verify Service set up in your Twilio account. You can then use the twilioVerifySid field under sms to provide the necessary SID.




 
Twilio Verify SID (object) or Twilio Phone Number (object) or Twilio Caller ID (object) or Telesign Service (object)
Method for making voice calls. Choose one method for making voice calls based on your telephony provider setup.


 
One of:
Method for making voice calls. Choose one method for making voice calls based on your telephony provider setup.


twilioVerifySid
string
The Twilio Verify Service SID used for sending verification messages or calls. You can find this value in your Twilio console.


This method uses Twilio's Verify API.


 
Twilio Verify SID (object) or Twilio Phone Number (object) or Twilio Message SID (object) or Telesign Service (object)
Method for sending SMS messages. Choose one method for sending SMS messages based on your telephony provider setup.


 
One of:
Method for sending SMS messages. Choose one method for sending SMS messages based on your telephony provider setup.


twilioVerifySid
string
The Twilio Verify Service SID used for sending verification messages or calls. You can find this value in your Twilio console.


This method uses Twilio's Verify API.


 
providerSid
string
The account string identifier (SID) for your telephony provider account. Your telephony provider gives you this SID.


 
Responses 
201
Created


403
Forbidden


post/api/v1/telephony-providers
Request samples 
application/json
{
  • "providerAuthToken": "11a9b6c435967abe806f4f0d6ec0f382",
  • "providerCapability": "ALL",
  • "providerName": "TWILIO",
  • "providerSid": "ACb49fb19a09b2f5d2f121fe1c207689dt",
  • "providerSettings": {
    • "sms": {
      },
    • "call": {
      }
    }
}
Response samples 
application/json
{
  • "id": "oct3v00k4iOFlEJmQ806",
  • "isPrimaryProvider": true,
  • "enabled": true,
  • "providerCapability": "ALL",
  • "providerName": "TWILIO",
  • "providerSid": "ACb49fb19a09b2f5d2f121fe1c207689dt",
  • "providerSettings": {
    • "sms": {
      },
    • "call": {
      }
    }
}
Retrieve a custom telephony provider
Early AccessIdentity Engine
OAuth 2.0 scope: 
  • okta.customTelephonyProvider.read
Retrieves the details of a custom telephony provider by its ID


Request 
path Parameters
customTelephonyProviderId
required
string
The ID of the custom telephony provider


 
Responses 
200
OK


403
Forbidden


404
Not Found


get/api/v1/telephony-providers/{customTelephonyProviderId}
Request samples 
Response samples 
application/json
{
  • "id": "oct3v00k4iOFlEJmQ806",
  • "isPrimaryProvider": true,
  • "enabled": true,
  • "providerCapability": "ALL",
  • "providerName": "TWILIO",
  • "providerSid": "ACb49fb19a09b2f5d2f121fe1c207689dt",
  • "providerSettings": {
    • "sms": {
      },
    • "call": {
      }
    }
}
Update a custom telephony provider credential
Early AccessIdentity Engine
OAuth 2.0 scope: 
  • okta.customTelephonyProvider.manage
Updates the credentials of an existing custom telephony provider


Request 
path Parameters
customTelephonyProviderId
required
string
The ID of the custom telephony provider


 
Request Body schema: application/json
required
id
string
ID of the custom telephony provider


 
providerAuthToken
string
The authentication token that's used to authenticate requests to the telephony provider. Your telephony provider gives you this token.


 
object (CustomTelephonyProviderSettings) 
Settings for custom telephony provider.


These settings vary based on the telephony provider and the type of telephony operation (SMS or Voice). For sms and call, you can select one method per telephony operation (sms and call) for sending messages or voice calls.




Note: Configure your telephony provider settings before selecting the methods for sending SMS messages or making voice calls. For example, if you select Twilio as your telephony provider, and you want to send SMS messages using Twilio's Verify Service, ensure that you have the Verify Service set up in your Twilio account. You can then use the twilioVerifySid field under sms to provide the necessary SID.




 
Twilio Verify SID (object) or Twilio Phone Number (object) or Twilio Caller ID (object) or Telesign Service (object)
Method for making voice calls. Choose one method for making voice calls based on your telephony provider setup.


 
One of:
Method for making voice calls. Choose one method for making voice calls based on your telephony provider setup.


twilioVerifySid
string
The Twilio Verify Service SID used for sending verification messages or calls. You can find this value in your Twilio console.


This method uses Twilio's Verify API.


 
Twilio Verify SID (object) or Twilio Phone Number (object) or Twilio Message SID (object) or Telesign Service (object)
Method for sending SMS messages. Choose one method for sending SMS messages based on your telephony provider setup.


 
One of:
Method for sending SMS messages. Choose one method for sending SMS messages based on your telephony provider setup.


twilioVerifySid
string
The Twilio Verify Service SID used for sending verification messages or calls. You can find this value in your Twilio console.


This method uses Twilio's Verify API.


 
providerSid
string
The account string identifier (SID) for your telephony provider account. Your telephony provider gives you this SID.


 
Responses 
200
OK


403
Forbidden


404
Not Found


patch/api/v1/telephony-providers/{customTelephonyProviderId}
Request samples 
application/json
{
  • "id": "oct3v00k4iOFlEJmQ806",
  • "providerAuthToken": "11a9b6c435967abe806f4f0d6ec0f382",
  • "providerSid": "ACb49fb19a09b2f5d2f121fe1c207689dt",
  • "providerSettings": {
    • "sms": {
      },
    • "call": {
      }
    }
}
Response samples 
application/json
{
  • "id": "oct3v00k4iOFlEJmQ806",
  • "isPrimaryProvider": true,
  • "enabled": true,
  • "providerCapability": "ALL",
  • "providerName": "TWILIO",
  • "providerSid": "11a9b6c435967abe806f4f0d6ec0f382",
  • "providerSettings": {
    • "sms": {
      },
    • "call": {
      }
    }
}
Delete a custom telephony provider
Early AccessIdentity Engine
OAuth 2.0 scope: 
  • okta.customTelephonyProvider.manage
Deletes a custom telephony provider by its ID.


Before you delete a provider, ensure that it is deactivated. Consider setting up another telephony provider if you still plan to use telephony in your org. See Set up an external telephony provider.


Request 
path Parameters
customTelephonyProviderId
required
string
The ID of the custom telephony provider


 
Responses 
204
No Content


403
Forbidden


404
Not Found


delete/api/v1/telephony-providers/{customTelephonyProviderId}
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}
Activate a custom telephony provider
Early AccessIdentity Engine
OAuth 2.0 scope: 
  • okta.customTelephonyProvider.manage
Activates a custom telephony provider by its ID. You must activate a provider before it can be used.


Request 
path Parameters
customTelephonyProviderId
required
string
The ID of the custom telephony provider


 
Responses 
200
OK


403
Forbidden


404
Not Found


post/api/v1/telephony-providers/{customTelephonyProviderId}/lifecycle/activate
Request samples 
Response samples 
application/json
{
  • "id": "oct3v00k4iOFlEJmQ806",
  • "isPrimaryProvider": true,
  • "enabled": true,
  • "providerCapability": "ALL",
  • "providerName": "TWILIO",
  • "providerSid": "ACb49fb19a09b2f5d2f121fe1c207689dt",
  • "providerSettings": {
    • "sms": {
      },
    • "call": {
      }
    }
}
Deactivate a custom telephony provider
Early AccessIdentity Engine
OAuth 2.0 scope: 
  • okta.customTelephonyProvider.manage
Deactivates a custom telephony provider by its ID. Keep the following points in mind when you deactivate a provider:


    

  • You must deactivate a provider before deleting it.
    • 

  • If you have two telephony providers configured, and both are active, you can only deactivate the secondary provider. The second provider is the one that isn't set as the primary provider.
    • 



Request 
path Parameters
customTelephonyProviderId
required
string
The ID of the custom telephony provider


 
Responses 
200
OK


403
Forbidden


404
Not Found


post/api/v1/telephony-providers/{customTelephonyProviderId}/lifecycle/deactivate
Request samples 
Response samples 
application/json
{
  • "id": "oct3v00k4iOFlEJmQ806",
  • "isPrimaryProvider": false,
  • "enabled": false,
  • "providerCapability": "ALL",
  • "providerName": "TWILIO",
  • "providerSid": "ACb49fb19a09b2f5d2f121fe1c207689dt",
  • "providerSettings": {
    • "sms": {
      },
    • "call": {
      }
    }
}
Set a custom telephony provider as a primary telephony provider
Early AccessIdentity Engine
OAuth 2.0 scope: 
  • okta.customTelephonyProvider.manage
Sets a custom telephony provider as the primary telephony provider for the org. You can only set one provider as a primary provider at a time.


Request 
path Parameters
customTelephonyProviderId
required
string
The ID of the custom telephony provider


 
Responses 
200
OK


403
Forbidden


404
Not Found


post/api/v1/telephony-providers/{customTelephonyProviderId}/setAsPrimary
Request samples 
Response samples 
application/json
{
  • "id": "oct3v00k4iOFlEJmQ806",
  • "isPrimaryProvider": true,
  • "enabled": true,
  • "providerCapability": "ALL",
  • "providerName": "TWILIO",
  • "providerSid": "ACb49fb19a09b2f5d2f121fe1c207689dt",
  • "providerSettings": {
    • "sms": {
      },
    • "call": {
      }
    }
}
Send a test message from a custom telephony provider
Early AccessIdentity Engine
OAuth 2.0 scope: 
  • okta.customTelephonyProvider.manage
Sends a test message (SMS or call) using the specified custom telephony provider to verify that the provider is configured correctly.


You must provide a valid phone number and country code to send the test message. Send it to a phone number that you have access to so you can confirm that the message was received.


Request 
path Parameters
customTelephonyProviderId
required
string
The ID of the custom telephony provider


 
Request Body schema: application/json
required
countryCodeIso2
string
The country code for the phone number.
Use the Alpha-2 code from ISO 3166-1 for country codes.


 
factor
string
The type of test message to send


 Enum: "SMS" "CALL"  
phoneNumber
string
The phone number to which the test message or call is sent


 
Responses 
204
No Content


400
Bad Request


403
Forbidden


post/api/v1/telephony-providers/{customTelephonyProviderId}/test
Request samples 
application/json
{
  • "factor": "SMS",
  • "phoneNumber": "+1234567890",
  • "countryCodeIso2": "US"
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}