From 340483dce47928d0b6b3bbfbc69e81fd8d922c15 Mon Sep 17 00:00:00 2001 From: ajkamen Date: Thu, 30 Jul 2026 11:00:15 -0700 Subject: [PATCH 1/2] docs: clarify Digital API authentication and limits --- docs/basics/access-token.md | 37 +++++++++++++------------ docs/basics/auth.md | 54 +++++++++++++++---------------------- docs/basics/requests.md | 53 ++++++++++++++++++++++++++---------- docs/basics/responses.md | 42 ++++++++++++++++++----------- 4 files changed, 104 insertions(+), 82 deletions(-) diff --git a/docs/basics/access-token.md b/docs/basics/access-token.md index 6d479b6..c4b7211 100644 --- a/docs/basics/access-token.md +++ b/docs/basics/access-token.md @@ -1,29 +1,28 @@ -# Obtain an Access Token +# Obtain an API Access Token -Welcome to the RingCX Developer Platform where you can create amazing, automated, scalable customer experiences. Before you begin building your RingCX application, you will need to obtain an Access Token. +Before calling the RingCX Digital REST API, create an API access token for your application. -## What is an Access Token used for? +## How API access tokens work -A RingCX Access Token is used to access the RingCX REST API. Developers transmit their access token with every request as a means of authentication. +An API access token authenticates requests to the RingCX Digital REST API. The token is associated with a RingCX Digital user, and API requests made with the token act with that user's permissions. -The permissions bound to an access token are inherited from the associated user. +An API access token remains valid while it is enabled. Disable or delete a token when the integration no longer requires access. -## How to obtain an Access Token? +!!! warning "Protect API access tokens" + Treat an API access token like a password. Store it in a secrets manager or environment variable, do not commit it to source control, and do not include it in logs or URLs. -A RingCX Access Token is provisioned through the RingCX user interface. Each token is assigned a description/label to help administrators keep better track of the tokens they have provisioned. In addition, each token is associated with a user within your RingCX account. When the token is used, all actions performed will be attributed to the associated user. +## Create an API access token -To obtain a token, follow these steps: +You must have the **Manage API access tokens** permission to create or manage API access tokens. -1. Login to your RingCX portal and click on the "Admin" menu located in the top, horizontal menu. - -2. Select "API access tokens" towards the bottom of the left hand menu. - -3. You should see a list of access tokens if any have been provisioned. Select the token, or click the "+" button to create a new one. - -4. Finally, enter a label/description for your token, and select an Agent on which the token will act on behalf of. Make sure the token is "enabled" and click "Save." - - ![API access token](../img/api-token.png) +1. Sign in to RingCX Digital and open **Admin**. +2. Select **API access tokens**. +3. Click **+** to create a token. +4. Enter a descriptive name and select the user the integration will act on behalf of. +5. Make sure the token is enabled, and then save it. -## How do I transmit the token to the RingCX REST API? +![API access token](../img/api-token.png) -To learn more about how to authenticate to the RingCX REST API, read the article on [Authentication](../auth/). +Use a dedicated user with only the permissions required by the integration. If that user's permissions change, the token's effective permissions change as well. + +To send the token with an API request, see [Authenticating to the RingCX Digital API](auth.md). diff --git a/docs/basics/auth.md b/docs/basics/auth.md index 2a02b50..ed2aa59 100644 --- a/docs/basics/auth.md +++ b/docs/basics/auth.md @@ -1,44 +1,32 @@ -# Authenticating to the RingCX API +# Authenticate to the RingCX Digital API -## Access Tokens +Every API request must include an API access token. Send the token in the HTTP `Authorization` header using the Bearer authentication scheme: -Every request must provide an access token to authenticate properly. - -Obtain an Access Token - -!!! note "Access Token Permissions" - Different API endpoints require different permissions. The permissions assocated with an access token are inherited from the associated user. Read about [creating an access token](../access-token/) to learn how to associate an access token with a user. - -## Transmitting an Access Token - -### Via Form Parameter - -An access token can be specified in a request parameter named `access_token`. - -#### Example - -To get all interventions on the source accessible by the token’s users, URL will looks like: - -`https://[YOUR DOMAIN].api.digital.ringcentral.com/1.0/interventions?access_token=abc42` - -### Via HTTP Header - -In order to be compliant with OAuth 2.0 standards an access token can also be specified via the `Authorization` request header where value respects following format: - -`Authorization: Bearer ` - -#### Example +```http +Authorization: Bearer +``` -To get all interventions on the source accessible by the token’s users, you’ll need to build your request with Authorization request header with proper value. HTTP request will looks like: +For example: ```http GET /1.0/interventions HTTP/1.1 -Host: test.api.digital.ringcentral.com -Authorization: Bearer abc42 +Host: {account-name}.api.digital.ringcentral.com +Authorization: Bearer +Accept: application/json +``` + +```bash +curl --request GET \ + --url "https://{account-name}.api.digital.ringcentral.com/1.0/interventions" \ + --header "Accept: application/json" \ + --header "Authorization: Bearer ${RINGCX_DIGITAL_ACCESS_TOKEN}" ``` -!!! warning "Keep access token secure" - Do not publish your access token publicly. The access token is **unencrypted**, and possession of it by a third-party will give them access to your account. +Replace `{account-name}` with your RingCX Digital account name. Set `RINGCX_DIGITAL_ACCESS_TOKEN` in your local environment; do not place the token directly in source code. +!!! note "Permissions" + The token uses the permissions of its associated user. An authenticated request returns `403 Forbidden` when that user does not have the permission required by the endpoint or resource. +The API also accepts an `access_token` request parameter for compatibility with existing integrations. Use the Bearer header for new integrations because URLs can be stored in browser history, proxy logs, and server access logs. +To create a token, see [Obtain an API Access Token](access-token.md). diff --git a/docs/basics/requests.md b/docs/basics/requests.md index 2e42df4..8a21d91 100644 --- a/docs/basics/requests.md +++ b/docs/basics/requests.md @@ -2,36 +2,61 @@ RingCX Digital provides a REST JSON API to retrieve, create, and manipulate data from third-party applications. -!!! tip "Test in your browser" - The RingCX API can easily be tested from any web browser or command line terminal. - !!! tip "Using this Guide" - Throughout this Developer Guide you will see sample endpoint URLs. These URLs all contain a placeholder string of `[YOUR DOMAIN]`. When developing, be sure to replace this string with your assigned domain. + Endpoint URLs use the `{account-name}` placeholder. Replace it with your RingCX Digital account name. ## Building an HTTP Request -### Scheme and hostname +### Base URL + +Send API requests over HTTPS using your account-specific API hostname: + +```text +https://{account-name}.api.digital.ringcentral.com +``` + +For example, if your account name is `example`, the base URL is: + +```text +https://example.api.digital.ringcentral.com +``` -Request must be done with HTTPS scheme. Hostname is determined from your application name. If your application name is "example," then the API hostname will be: `example.api.engagement.dimelo.com`. +Use the hostname assigned to your account if it differs from this format. + +### Versioned path + +Append the versioned path shown in the API reference. Most endpoints in this reference use the `/1.0` prefix: + +```text +https://{account-name}.api.digital.ringcentral.com/1.0/users/me +``` + +Do not substitute one API version for another. Request and response contracts can differ between versions. ### HTTP method -As it is specified in the API methods list, HTTP method can be GET, POST, PUT or DELETE. +Use the HTTP method shown for the operation in the API reference. Depending on the operation, the method can be `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`. + +### Headers -### URL path +Send the API access token in the `Authorization` header. For requests with a JSON body, also send `Content-Type: application/json`. -All API paths are prefixed by `/1.0`. This is the version of RingCX Digital Rest API. +```http +Accept: application/json +Authorization: Bearer +Content-Type: application/json +``` -#### Multiple parameters +### Array parameters -Some API methods described below take extra parameters. Some of them are multiple (example: category_ids, tags_ids or some custom fields). You must add double brackets [], after the parameters name. +Some query and form parameters accept multiple values. Append `[]` to the parameter name and repeat the parameter for each value. Examples: * `?firstname=john&category_ids[]=4242&category_ids[]=2854` -* `tag_ids[]=1&tag_ids[]=2` -* `custom_field_values[multiple_custom_field_key][]=value1&custom_field_values[multiple_custom_field_key][]=value2&custom_field_values[multiple_custom_field_key][]=value3` +* `?tag_ids[]=1&tag_ids[]=2` +* `?custom_field_values[multiple_custom_field_key][]=value1&custom_field_values[multiple_custom_field_key][]=value2` ## Authentication -See [Authenticating to the RingCX API](../auth/) +See [Authenticate to the RingCX Digital API](auth.md). diff --git a/docs/basics/responses.md b/docs/basics/responses.md index 122ef2a..006e20f 100644 --- a/docs/basics/responses.md +++ b/docs/basics/responses.md @@ -1,6 +1,6 @@ -# RingCX API Responses +# RingCX Digital API Responses -All responses are formatted in JSON, with the exception of a few errors. Here is an example: +API responses use JSON. For example: ```json { @@ -11,39 +11,49 @@ All responses are formatted in JSON, with the exception of a few errors. Here is } ``` -### Encoding +## Response format -All responses are formatted using UTF-8 encoding. +Responses use UTF-8 encoding and the following content type: -### Content type - -The returned content-type is : `application/json; charset=utf-8`. +```http +Content-Type: application/json; charset=utf-8 +``` ## Errors -In case of a fatal error, a response is sent in JSON (application/json; charset=utf-8 content type) with an HTTP status code different than 200. - -All errors rendered respects following format: +API errors use a non-2xx HTTP status and the following JSON structure: ```json { - "error": "Error identifier", - "message": "A text message that describes the error", + "error": "error_identifier", + "message": "A description of the error", "status": 400 } ``` -## Throttling +Common error statuses include: + +| Status | Meaning | +|--------|---------| +| `400` | The request is malformed or contains an invalid parameter. | +| `403` | Authentication is required, or the token's user is not authorized to perform the operation. | +| `404` | The requested resource does not exist or is not accessible to the token's user. | +| `409` | The request conflicts with the current resource state. | +| `422` | The request is valid JSON but cannot be processed with the supplied values. | +| `429` | The applicable request limit has been exceeded. | + +## Rate limits -The number of queries is limited, the maximum is set to 500 queries per minute, otherwise you will hit the limit. +The default account-level limit is 500 API requests per minute. An account can be configured with a different limit, and selected operations can have a token-specific limit. When a token-specific limit applies, requests using that token are counted separately for those operations. -In case you reach the limit the server responds with 429 and the following JSON will be returned: +When the applicable limit is exceeded, the API returns `429 Too Many Requests`. The error message states the limit that was applied: ```json { "error": "rate_limit_exceeded", - "message": "Rate limit exceeded", + "message": "Rate limit exceeded (500 requests per minute max)", "status": 429 } ``` +Applications should limit request concurrency, avoid unnecessary polling, and wait before retrying a rate-limited request. From db30675ddff3e6102d0cf8776082c6c1066bf0f2 Mon Sep 17 00:00:00 2001 From: ajkamen Date: Tue, 25 Aug 2026 09:28:48 -0700 Subject: [PATCH 2/2] docs: correct API token creation flow --- docs/basics/access-token.md | 9 +++------ docs/basics/auth.md | 2 +- docs/interactions/quick-start.md | 10 +--------- docs/interactions/structured-messages/quick-start.md | 12 +----------- docs/routing/quick-start.md | 10 +--------- 5 files changed, 7 insertions(+), 36 deletions(-) diff --git a/docs/basics/access-token.md b/docs/basics/access-token.md index c4b7211..05ce76e 100644 --- a/docs/basics/access-token.md +++ b/docs/basics/access-token.md @@ -4,7 +4,7 @@ Before calling the RingCX Digital REST API, create an API access token for your ## How API access tokens work -An API access token authenticates requests to the RingCX Digital REST API. The token is associated with a RingCX Digital user, and API requests made with the token act with that user's permissions. +An API access token authenticates requests to the RingCX Digital REST API. RingCX Digital automatically associates each new token with the account's default administrator user, which has all API permissions. An API access token remains valid while it is enabled. Disable or delete a token when the integration no longer requires access. @@ -18,11 +18,8 @@ You must have the **Manage API access tokens** permission to create or manage AP 1. Sign in to RingCX Digital and open **Admin**. 2. Select **API access tokens**. 3. Click **+** to create a token. -4. Enter a descriptive name and select the user the integration will act on behalf of. -5. Make sure the token is enabled, and then save it. +4. Enter a descriptive name, make sure the token is enabled, and then save it. -![API access token](../img/api-token.png) - -Use a dedicated user with only the permissions required by the integration. If that user's permissions change, the token's effective permissions change as well. +Create a separate token for each integration so that you can disable or delete its access independently. To send the token with an API request, see [Authenticating to the RingCX Digital API](auth.md). diff --git a/docs/basics/auth.md b/docs/basics/auth.md index ed2aa59..90b5b91 100644 --- a/docs/basics/auth.md +++ b/docs/basics/auth.md @@ -25,7 +25,7 @@ curl --request GET \ Replace `{account-name}` with your RingCX Digital account name. Set `RINGCX_DIGITAL_ACCESS_TOKEN` in your local environment; do not place the token directly in source code. !!! note "Permissions" - The token uses the permissions of its associated user. An authenticated request returns `403 Forbidden` when that user does not have the permission required by the endpoint or resource. + RingCX Digital automatically associates each API access token with the account's default administrator user, which has all API permissions. The API also accepts an `access_token` request parameter for compatibility with existing integrations. Use the Bearer header for new integrations because URLs can be stored in browser history, proxy logs, and server access logs. diff --git a/docs/interactions/quick-start.md b/docs/interactions/quick-start.md index 131da4b..59f771b 100644 --- a/docs/interactions/quick-start.md +++ b/docs/interactions/quick-start.md @@ -11,15 +11,7 @@ The first thing you need to do is obtain an API Access Token if you do not alrea ??? tip "How to generate a RingCX API access token" - 1. Login to your RingCX portal and click on the "Admin" menu located in the top, horizontal menu. - - 2. Select "API access tokens" towards the bottom of the left hand menu. - - 3. You should see a list of access tokens if any have been provisioned. Select the token, or click the "+" button to create a new one. - - 4. Finally, enter a label/description for your token, and select an Agent on which the token will act on behalf of. Make sure the token is "enabled" and click "Save". - - ![API access token](../img/api-token.png) + Follow [Obtain an API Access Token](../basics/access-token.md) to create and secure a token for your integration. Make note of the access token generated as you will need it later. diff --git a/docs/interactions/structured-messages/quick-start.md b/docs/interactions/structured-messages/quick-start.md index ebdfe46..9817af3 100644 --- a/docs/interactions/structured-messages/quick-start.md +++ b/docs/interactions/structured-messages/quick-start.md @@ -113,17 +113,7 @@ The first thing you need to do is obtain an API Access Token if you do not alrea ??? tip "How to generate a RingCX API access token" - 1. Login to your RingCX portal and click on the "Admin" menu located in the top, horizontal menu. - - 2. Select "Dev tools" towards the bottom of the left hand menu. - - 3. Select "API access tokens" from the drawer that pops out. - - 3. You should see a list of access tokens if any have been provisioned. Select the token, or click the "Add" button to create a new one. - - 4. Finally, enter a label/description for your token, and select an Agent on which the token will act on behalf of. Make sure the token is "enabled" and click "Save." - - ![API access token](../../img/api-token-engage.png) + Follow [Obtain an API Access Token](../../basics/access-token.md) to create and secure a token for your integration. Make note of the access token generated as you will need it later. diff --git a/docs/routing/quick-start.md b/docs/routing/quick-start.md index 0643ad5..6fd197d 100644 --- a/docs/routing/quick-start.md +++ b/docs/routing/quick-start.md @@ -17,15 +17,7 @@ The first thing you need to do is obtain an API Access Token if you do not alrea ??? tip "How to generate a RingCX API access token" - 1. Login to your RingCX portal and click on the "Admin" menu located in the top, horizontal menu. - - 2. Select "API access tokens" towards the bottom of the left hand menu. - - 3. You should see a list of access tokens if any have been provisioned. Select the token, or click the "+" button to create a new one. - - 4. Finally, enter a label/description for your token, and select an Agent on which the token will act on behalf of. Make sure the token is "enabled" and click "Save." - - ![API access token](../img/api-token.png) + Follow [Obtain an API Access Token](../basics/access-token.md) to create and secure a token for your integration. Make note of the access token generated as you will need it later.