This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Legacy API authentication (deprecated)

Important

The API authentication endpoint and procedure described in this section is deprecated. Implement authentication for your Toast API integration using the endpoint and procedure described in Authentication and restaurant access.

You get an authentication token by sending a POST request to the /usermgmt/v1/oauth/token resource of the Toast user management API. The following example shows the URL of the user management token endpoint.

https://[toast-api-hostname]/usermgmt/v1/oauth/token

You must include your client identifier and client secret string in the message body of a POST request for an authentication token. When the user management API determines that the client identifier and client secret string are valid, it returns an authentication token along with a set of data describing the way you can use it. You receive a client identifier (client_id) and client secret string (client_secret) when you register to use Toast APIs. For more information, see Toast API accounts.

To create the message body of an authentication request, concatenate your client identifier, client secret string, and the grant type (which is always grant_type=client_credentials) using the syntax for a set of query parameters:

  • The grant_type is always grant_type=client_credentials.

  • Include the client identifier in the client_id parameter.

  • Include the client secret string in the client_secret parameter.

Important

You must URL encode the values of each parameter to replace special characters that interfere with processing the string of query parameters.

The following example shows a concatenated string of the grant_type, client_id, and client_secret parameters.

grant_type=client_credentials&client_id=my-identifier&client_secret=XwEW%3C%3CvR*k6%3B%23Fp8

Note

You must use query parameter syntax for API client credentials, even though you submit them in the message body of a POST authentication request.

The following curl command requests an authentication token from the usermgmt/v1/oauth/token resource. For more information about the curl utility, see https://curl.haxx.se/.

curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=my-identifier&client_secret=XwEW%3C%3CvR*k6%3B%23Fp8" \
https://[toast-api-hostname]/usermgmt/v1/oauth/token

The return data that you receive depends on the type of Toast API client you are using. Toast APIs support partner clients and restaurant management group clients. For more information about the types of Toast API clients, see Toast API accounts.

The following sections provide information about the return data provided for authentication requests for different Toast API client types.