ringcentral · ajkamen · Jul 30, 2026 · Aug 25, 2026
diff --git a/docs/basics/access-token.md b/docs/basics/access-token.md
@@ -1,29 +1,25 @@
-# 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. RingCX Digital automatically associates each new token with the account's default administrator user, which has all API 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, make sure the token is enabled, and then save it.
 
-## How do I transmit the token to the RingCX REST API?
+Create a separate token for each integration so that you can disable or delete its access independently.
 
-To learn more about how to authenticate to the RingCX REST API, read the article on [Authentication](../auth/).
+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
@@ -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.
-
-<a class="btn btn-primary" href="../access-token/">Obtain an Access Token</a>
-
-!!! 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 <access_token_value>`
-
-#### Example
+```http
+Authorization: Bearer <access-token>
+```
 
-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 <access-token>
+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"
+    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.
 
+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
@@ -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 <access-token>
+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
@@ -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.
diff --git 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
@@ -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
@@ -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.