Phone.com API Security

The Phone.com API supports multiple standards to secure API communications and protect your Phone.com data. This topic outlines permission and authentication settings, and offers guidelines on protecting your application.

If you have questions on security that are not addressed here, please contact the Phone.com API Support team at 1-844-PHONE-API (1-844-746-6327) or at api@phone.com.

In This Topic:

Accessing Resources Through the Phone.com API

With a Phone.com API Developer account, you can associate any number of your applications with your Phone.com account. Each application, however, is considered separate and identified by Phone.com using a unique API key.

The applications you build on our API services can do the following:

  • Access all of your account resources using the appropriate API requests. Resources include your phone extensions; the greetings, menus, queues and routes used to control calls and SMS messages; your contacts and contact groups; and your routing schedules. Note: These resources can also be viewed, configured and managed through our Telephony Toolkit by logging into your account.
  • Make phone calls and send SMS messages from your application through our API.
  • Receive calls and SMS messages directed through our API to your application server.

Resources like greetings, menus and queues can be shared among multiple phone numbers in your account, and accessed from any one of your applications. If, however, you need to isolate specific resources so that certain applications cannot reach them, you will need to place those resources in a separate Phone.com account. Apps linked to one account are not allowed to access resources in another account.

API Key and Password Security

When you configure an application in your Phone.com API Developer account, our system automatically generates an API key for your app. Note that an application’s API key cannot be changed once it is set.

To authenticate an API request from your application, you must provide a valid API key and a valid API password. Your application’s API password, set when you configure the app in your account settings, can be changed at any time. If you are concerned that your application’s API password may have been compromised, you can change it by logging into your account and clicking API > Manage Applications > Edit.

Important: Note that your app’s API password is different from your Phone.com API Developer account password, which you can also change (My Account > Account Information > Change Password). The API password allows your app to access resources through the Phone.com API; your API Developer account password allows you to log into your account to manage resources and account settings in the Telephony Toolkit.

Account Security

Logging into your Phone.com API Developer account and using features in the Telephony Toolkit requires an HTTPS connection. Also, the toolkit relies on cookies to maintain sessions.

When communicating with the Public Switched Telephone Network (PSTN), which is outside of the Phone.com network, please note that SIP and RTP traffic are not encrypted.

Security at the Protocol Level

The Phone.com API uses the Basic authentication scheme of the HTTP protocol. The username must be set to your application’s API key and the password to your app’s API password.

The realm parameter is set by our API server to Phone.com API. For example:

Example:
WWW-Authenticate: Basic realm="Phone.com API"

Because the Basic authentication scheme doesn’t secure or encrypt the password, all requests must be sent using SSL (HTTPS protocol). You cannot access the Phone.com API using plain HTTP.

If your application sends a request without correct authentication or the request header is not properly formed, the Phone.com API server will reply with an HTTP 401 Unauthorized error. The extended error code in the body of the response will indicate the specific error. If the header is present and correctly formed but the system is not able to validate the credentials, the server will also return an HTTP 401 code. Correcting the API key and/or the API password should resolve the error.

HTTP Event Security

When invoked asynchronously, a set of API commands will result in HTTP event messages being sent to the main and fallback URLs specified in your application settings (the fallback URL being optional). We strongly recommend that you set these webservers to only accept requests from the Phone.com API network (on IP Subnet: 72.1.46.0/24).

The HTTP event messages that Phone.com may send to your main and fallback URLs can also include user information (including phone numbers), DTMF digits and other potentially sensitive data. For this reason, we strongly recommend that you configure your webserver to support HTTPS, and to configure your application’s main and fallback URLs to use HTTPS. This will encrypt the communication between Phone.com and your webserver.

State Data Encryption

The Phone.com API’s /calls service allows you provide state data, to be returned in HTTP events. We recommend that no sensitive data be included in this transmission, and that you consider encrypting state data. Phone.com stores this data while the request is being processed and discards it shortly after the request completes.

Cross-site Scripting

In an effort to prevent cross-site scripting (XSS) vulnerabilities, our API server will reject requests that contain any HTML tags. The server will respond to such requests with an HTTP 400 Invalid Request error, with the Extended Error Code 10030.

Learn More: