diff --git a/docs/basics/access-token.md b/docs/basics/access-token.md index 6d479b6..05ce76e 100644 --- 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 index 2a02b50..90b5b91 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" + 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 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. 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.