Control API

Ably Control API is a REST API that enables you to manage your Ably account programmatically. The Control API also enables you to build web apps and command-line tools, to create and manage your Ably realtime infrastructure. Details of the API can be found in the Control API Reference.

Using the Control API you can automate the provisioning, management, and testing of your Ably realtime infrastructure. You can dynamically create Ably apps, configure them, and delete them if necessary. You can implement multi-tenancy solutions for your customers, and create configuration-driven environments that can easily be replicated under programmatic control. Once these environments are created you can also test them using Control API.

With the Control API you can create and manage:

• Your Ably apps
• API keys for an Ably app
• Namespaces (for channel rules)
• Queues
• Integration rules

Repetitive operations such as creating, updating or deleting Ably apps, enumerating queues, creation of rules, and other tasks that would be time-consuming to carry out manually, can be automated using the Control API.

The following diagram illustrates an example use case:

In this use case, Control API is used to provision a sample app for review and testing purposes. Once provisioned, the realtime or REST API can be used to test the app as needed. Once fully tested, the Control API can be used to replicate the app for users as required, using the known-good configuration.

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.

Note that the Control API has certain limits on the number of API calls that can be made per hour.

Control API is currently in Preview.

The OpenAPI document for this API can be found in the Ably OpenAPI Documents GitHub repository. It is not required in order to use Control API, but is provided to you so you may optionally generate your own documentation in the tool of your choice, or use mocking tools such as Prism to assist in developing your clients.

In the testing with Postman section you learn how to import this OpenAPI document into Postman, to enable you to quickly try out Control API.

Using the code-generation capabilities of tools such as Postman or Paw you can build clients to manage your realtime apps with a minimum of development effort.

Before you can use the Control API you must create an access token to authenticate with. You can do this in the Ably 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:

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

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.

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 `<YOUR_ACCESS_TOKEN>` with the token you have copied to the clipboard:

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

Copy
Copied!

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>'

Copy
Copied!

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"
    }
}

Copy
Copied!

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

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

Your account settings are displayed. From here you can obtain your Ably account ID, as shown in the following screenshot:

You’ll need your account ID for account-level Control API requests, such as listing all the apps in your Ably account.

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

The “App ID” is displayed under “Application settings”. It is also the first part of your API key for that app. For example, if your API key is 28AB6c.DEFi0Q, then the App ID is 28AB6c. You can find out more in the Ably Help Center article what is an app API key?.

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):

To create an app:

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
}'

Copy
Copied!

Sample response:

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

Copy
Copied!

To list all the Ably apps associated with your account:

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

Copy
Copied!

Sample response:

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

Copy
Copied!

• Control API Reference
• Test the API with Postman
• Curl examples
• Manage apps with the Ably Control API GitHub Action