Control API

The Control API is a REST API that enables you to manage your Ably account programmatically.

Using the Control API you can manage:

Repetitive operations such as creating or updating applications, enumerating queues, and other tasks can be automated using the Control API.

In order to use the Control API you must first create an access token in the Ably dashboard. You can then use the Control API to manage many account functions without having to interact with the dashboard.

Development status

Control API is currently in Beta.

OpenAPI (OAS3) document

The OpenAPI (OAS3) document for this API can be found in the Ably OpenAPI Documents GitHub repository.

Authentication

Before you can use the Control API you must create an access token to authenticate with. You can do this in the Dashboard.

In the Ably dashboard, on the top menu bar, select your account from the dropdown list and then select “My Access Tokens” from the menu:


My Settings

You are presented with the “My Access Tokens” area, where you can create tokens for use with the Control API:


My Settings

Creating an access token

To create a new token, click the “Create new access token” button. Then enter the required information into the dialog:

1. Enter a memorable name for your token.
2. Select the capabilities you wish the token to have, depending on your use case.
3. Click the “Create” button to create the token.


My Settings

Using the access token

From the “My access tokens” area you can click the “Copy Token” button, to copy the token to the clipboard.

You use the access token to authenticate requests to the Control API. To do this, you supply the access token as a Bearer token in the Authorization header of the HTTP request. For example, in the following Curl request replace `` with the token you have copied to the clipboard:

curl -H 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' ...

Obtain token details using the Control API

You can use the Control API to obtain information about your access token, such as its capabilities and the user and account it is assigned to. This is shown in the following request:

curl --location --request GET 'https://control.ably.net/v1/me' \
--header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>'

Sample response:

{
    "token": {
        "id": "a975eecd-b189-4f5b-9f07-1197f3407193",
        "name": "Control API - new token",
        "capabilities": [
            "write:namespace",
            "read:namespace",
            "write:queue",
            "read:queue",
            "write:rule",
            "read:rule",
            "write:key",
            "read:key",
            "write:app",
            "read:app"
        ]
    },
    "user": {
        "id": 12140,
        "email": "[email protected]"
    },
    "account": {
        "id": "VgQpOZ",
        "name": "Free account"
    }
}

Account and application IDs

Operations that affect your entire account, such as listing the applications associated with that account, require an Account ID. Those that affect individual applications, such as creating an API key, require an Application ID.

How to find your Account ID

In the Ably dashboard, on the top menu bar, select your account from the dropdown list and then select “Account settings”:


Account Settings

Your Account Settings are displayed.

How to find your Application ID

In the Ably dashboard select the app you want to find the application ID for. Click on the “Settings” tab:


Application Settings

The App ID is displayed under “Application settings”. It is also the first part of your API key for that application. For example, if your API key is 28AB6c.DEFi0Q, then the App ID is 28AB6c. You can find out more in this Ably knowledge base article.

Quickstart

In the code examples, you will need to set the following variables by any convenient method (such as setting the variables in a script, or copying and pasting suitable values directly into the code):

Variable Description
ACCOUNT_ID Your Ably Account ID (see here)
ACCESS_TOKEN Your Ably access token for the Control API (see here)
APP_ID The ID of the application you want to modify (see here)

Create an application

To create an application:

curl --location --request POST 'https://control.ably.net/v1/accounts/${ACCOUNT_ID}/apps' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "name": "Created App 123",
    "status": "enabled",
    "tlsOnly": true,
    "fcmKey": null,
    "apnsCertificate": null,
    "apnsPrivateKey": null,
    "apnsUseSandboxEndpoint": false
}'

Sample response:

{
    "accountId": "VgQpOZ",
    "id": "bh4QSw",
    "name": "Created App 123",
    "status": "enabled",
    "tlsOnly": true,
    "apnsUseSandboxEndpoint": false,
    "created": 1625813276973,
    "modified": 1625813276973
}

List applications

To list all the Ably applications associated with your account:

curl "https://control.ably.net/v1/accounts/${ACCOUNT_ID}/apps" \
     --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header "Accept: application/json"

Sample response:

[
  {
      "accountId": "VgQpOZ",
      "id": "bh4QSw",
      "name": "Created App 123",
      "status": "enabled",
      "tlsOnly": true,
      "apnsUseSandboxEndpoint": false,
      "created": 1625813276973,
      "modified": 1625813276973
  },
  ...
]

Rate limits

The Control API has certain limits on the number of API calls that can be made per hour. The limits are as follows:

Authenticated Limit (requests per hour) Scope
True 4000 Limit is per account. The limit at the token level is 2000 calls per hour. This prevents an integration from using up all the limits.
False 60 Limit is by IP address

If you hit a rate limit you receive an error message, as shown in the following table:

Authenticated HTTP status code Message example
True 429 Rate limit exceeded; request rejected (nonfatal); metric = channel.maxRate; interval = 2021-05-11:12:43:6; permitted rate = 100; current rate = 100; scope = channel:[app:JrsUEQ:meta]channel.lifecycle
False 401 Unauthorized

See also


API reference
Documentation

Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.