Programmatic management with 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
• Account and app statistics
• 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.

OpenAPI document

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.

Authentication

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:

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.

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 <YOUR_ACCESS_TOKEN> 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 ID and app ID

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.

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:

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.

How to find your app ID

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?.

Examples

These examples demonstrate the use of the Control API with Curl.

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

Account

The only operation available at the account-level is to retrieve account-wide statistics.

To retrieve account-level statistics:

curl --request GET \
  --url 'https://control.ably.net/v1/accounts/${ACCOUNT_ID}/stats?unit=minute&limit=2' \
  --header 'Authorization: Bearer ${ACCESS_TOKEN}' \
  --header 'Content-Type: application/json'

See the API reference for information on the request body.

Sample response, with entries trimmed for readability:

[
  {
    "intervalId": "2024-10-17:08:45",
    "unit": "minute",
    "accountId": "VgQpOZ",
    "schema": "https://schemas.ably.com/json/account-stats-0.0.3.json",
    "entries": {
      "messages.all.all.count": 125,
      "messages.all.all.data": 349,
      "connections.all.peak": 502,
      "channels.peak": 37
    }
  },
  {
    "intervalId": "2024-10-17:08:44",
    "unit": "minute",
    "accountId": "VgQpOZ",
    "schema": "https://schemas.ably.com/json/account-stats-0.0.3.json",
    "entries": {
      "messages.all.all.count": 92,
      "messages.all.all.data": 279,
      "connections.all.peak": 472,
      "channels.peak": 36
    }
  }
]

Apps

You can use the Control API to perform tasks such as listing and creating Ably apps. Operations available include:

• Get a list of apps
• Create an app
• Update an app
• Delete an app
• Update an app's APNs info
• Retrieve app statistics

Create an app

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,
    "fcmServiceAccount": null,
    "fcmProjectId": null,
    "apnsCertificate": null,
    "apnsPrivateKey": null,
    "apnsUseSandboxEndpoint": false
}'

See the API reference for information on the request body.

Sample response:

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

List apps

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"

Sample response:

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

Retrieve app statistics

To retrieve app-level statistics:

curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID}/stats' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "unit": "hour",
    "limit": 1
}'

See the API reference for information on the request body.

Sample response, with entries trimmed for readability:

[
  {
    "intervalId": "2024-10-17:15",
    "unit": "hour",
    "appId": "pR4La5",
    "schema": "https://schemas.ably.com/json/app-stats-0.0.5.json",
    "entries": {
      "messages.all.all.count": 10293,
      "messages.all.all.data": 30879,
      "connections.all.peak": 510,
      "channels.peak": 68
    }
  }
]

Queues

You can use the Control API to manage Ably queues. The main operations are:

• List all Ably queues
• Create a queue
• Delete a queue

List queues

To list all queues associated with an app ID:

curl --location --request GET 'https://control.ably.net/v1/apps/${APP_ID}/queues' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'

Sample response:

[
    {
        "id": "28GY6a:us-east-1-a:Test",
        "appId": "28GY6a",
        "name": "Test",
        "region": "us-east-1-a",
        "amqp": {
            "uri": "amqps://us-east-1-a-queue.ably.io:5671/shared",
            "queueName": "28GY6a:Test"
        },
        "stomp": {
            "uri": "stomp://us-east-1-a-queue.ably.io:61614",
            "host": "shared",
            "destination": "/amqp/queue/28GY6a:Test"
        },
        "state": "Running",
        "messages": {
            "ready": 0,
            "unacknowledged": 0,
            "total": 0
        },
        "stats": {
            "publishRate": null,
            "deliveryRate": null,
            "acknowledgementRate": null
        },
        "ttl": 60,
        "maxLength": 10000,
        "deadletter": false,
        "deadletterId": "28GY6a:us-east-1-a:deadletter"
    },
    ...
]

Create a queue

To create a queue for an app:

curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID}/queues' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "name": "Queue 123",
    "ttl": 60,
    "maxLength": 10000,
    "region": "eu-west-1-a"
}'

See the API reference for information on the request body.

Sample response:

{
    "id": "28GY6a:eu-west-1-a:Queue 123",
    "appId": "28GY6a",
    "name": "Queue 123",
    "region": "eu-west-1-a",
    "amqp": {
        "uri": "amqps://eu-west-1-a-queue.ably.io:5671/shared",
        "queueName": "28GY6a:Queue 123"
    },
    "stomp": {
        "uri": "stomp://eu-west-1-a-queue.ably.io:61614",
        "host": "shared",
        "destination": "/amqp/queue/28GY6a:Queue 123"
    },
    "state": "Unknown",
    "messages": {
        "ready": 0,
        "unacknowledged": 0,
        "total": 0
    },
    "stats": {
        "publishRate": null,
        "deliveryRate": null,
        "acknowledgementRate": null
    },
    "ttl": 60,
    "maxLength": 10000,
    "deadletter": false,
    "deadletterId": "28GY6a:eu-west-1-a:deadletter"
}

Keys

You can use the Control API to manage Ably API keys. The main operations are:

• List all Ably API keys for an app
• Create a key
• Update a key
• Revoke a key

Control API enables you to create a key that has different capabilities for different channels.

List API keys

To list all keys associated with an app ID:

curl --location --request GET 'https://control.ably.net/v1/apps/${APP_ID}/keys' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'

Sample response:

[
    {
        "appId": "28GY6a",
        "id": "-frw5Q",
        "name": "Control API Key",
        "key": "28GY6a.-frw5Q:ZHTaEUGGJWJtHSkZ",
        "capability": {
            "channel-1": [
                "publish"
            ]
        },
        "created": 1630074457007,
        "modified": 1630074457007
    },
    ...
]

Create a key

The following example demonstrates how to create an Ably API key:

curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID}/keys' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "name": "My key name",
    "capability": {
        "channel1": [
            "publish",
            "subscribe"
        ],
        "channel2": [
            "history"
        ]
    }
}'

This request creates an API key with the key name My key name. Note that this key specifies different capabilities for each channel, for example, on channel1 this key has publish and subscribe capabilities. On channel2 the key only has the history capability.

Sample response:

{
    "appId": "28GY6a",
    "id": "Eg063g",
    "name": "My key name",
    "key": "28GY6a.Eg063g:Dp9ZNfK6Qr8aWy-q",
    "capability": {
        "channel1": [
            "publish",
            "subscribe"
        ],
        "channel2": [
            "history"
        ]
    },
    "created": 1630506079278,
    "modified": 1630506079278
}

Update a key

The following request updates the key name, and also adds the history capability to channel1:

curl --location --request PATCH 'https://control.ably.net/v1/apps/${APP_ID}/keys/${KEY_ID}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "name": "My key name UPDATED",
    "capability": {
        "channel1": [
            "publish",
            "subscribe",
            "history"
        ],
        "channel2": [
            "history"
        ]
    }
}'

Sample response:

{
    "appId": "28GY6a",
    "id": "RCSMrg",
    "name": "My key name UPDATED",
    "key": "28GY6a.RCSMrg:z8HkAtY7rMtnpcGq",
    "capability": {
        "channel1": [
            "history",
            "publish",
            "subscribe"
        ],
        "channel2": [
            "history"
        ]
    },
    "created": 1630507628335,
    "modified": 1630507811349
}

Revoke a key

To revoke a specific key for a specific app:

curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID/keys/${KEY_ID}/revoke' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'

In this case there is only a status code returned (200), or an error code.

Rules

You can use the Control API to manage Ably integration rules. The main operations are:

• List all rules for an app
• List details of a specific rule using rule ID
• Create a rule
• Update a rule
• Delete a rule

List rules

To list the rules for an app:

curl --location --request GET 'https://control.ably.net/v1/apps/${APP_ID}/rules' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'

Sample response:

[
    {
        "id": "oO-Tug",
        "appId": "28GY6a",
        "ruleType": "http",
        "requestMode": "single",
        "status": "disabled",
        "source": {
            "channelFilter": "",
            "type": "channel.message"
        },
        "target": {
            "url": "https://example.com/webhooks",
            "signingKeyId": null,
            "enveloped": true,
            "format": "json",
            "headers": [
                {
                    "name": "User-Agent",
                    "value": " user-agent-name"
                }
            ]
        },
        "version": "1.0",
        "created": 1626893758695,
        "modified": 1626894987810,
        "_links": {
            "self": "https://control.ably.net/v1/apps/28GY6a/rules/oO-Tug"
        }
    },
    ...
]

List a rule by rule ID

curl --location --request GET 'https://control.ably.net/v1/apps/${APP_ID}/rules/${RULE_ID}' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'

The rule details are returned for the specified rule.

Create a rule

The following example creates a rule with the following configuration:

The corresponding request is:

curl --location --request POST 'https://control.ably.net/v1/apps/${APP_ID}/rules' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "ruleType": "http",
    "requestMode": "single",
    "source": {
        "channelFilter": "^my-channel.*",
        "type": "channel.message"
    },
    "target": {
        "url": "https://example.com/webhooks",
        "format": "json",
        "headers": [
            {
                "name": "User-Agent",
                "value": "user-agent-string"
            },
            {
                "name": "headerName",
                "value": "headerValue"
            }
        ],
        "enveloped": true
    }
}'

Sample response:

{
    "id": "3DySkw",
    "appId": "28GY6a",
    "ruleType": "http",
    "requestMode": "single",
    "status": "enabled",
    "source": {
        "channelFilter": "^my-channel.*",
        "type": "channel.message"
    },
    "target": {
        "url": "https://example.com/webhooks",
        "signingKeyId": null,
        "enveloped": true,
        "format": "json",
        "headers": [
            {
                "name": "User-Agent",
                "value": "user-agent-string"
            },
            {
                "name": "headerName",
                "value": "headerValue"
            }
        ]
    },
    "version": "1.0",
    "created": 1630588265781,
    "modified": 1630588265781,
    "_links": {
        "self": "https://control.ably.net/v1/apps/28GY6a/rules/3DySkw"
    }
}

This shows the created webhook rule.

Update a rule

If you need to change a rule you can update it. For example, if you wanted to change the webhook endpoint URL you could carry out the following request:

curl --location --request PATCH 'https://control.ably.net/v1/apps/${APP_ID}/rules/${RULE_ID}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}' \
--data-raw '{
    "ruleType": "http",
    "target": {
        "url": "https://example.com/webhooks/webhook1"
    }
}'

The response is the same as for rule creation, but reflects the updated information.

Delete a rule

If you need to delete a rule you can:

curl --location --request DELETE 'https://control.ably.net/v1/apps/${APP_ID}/rules/${RULE_ID}' \
--header 'Authorization: Bearer ${ACCESS_TOKEN}'

In this case there is only a status code returned (204), or an error code.

Testing with Postman

The Control API is designed for programmatic access to your account. However, you can try out individual requests using either a command line tool such as Curl or HTTPie, or a graphical tool such as Postman or Paw. The following section shows you how to make requests using Postman.

Importing the OpenAPI document into Postman

A convenient way to try out the Control API is by importing the OpenAPI document into Postman, and then sending requests and checking the responses. To do this, perform the following steps:

1. Make sure you have Postman installed.

2. Start Postman and select File > Import from the main menu. The import dialog is displayed:

3. Click the Link tab, and paste in the following URL: https://raw.githubusercontent.com/ably/open-specs/main/definitions/control-v1.yaml, then click Continue:

4. In the Import dialog, use the default settings and click Import:

5. The imported document now appears in your Postman collections:

You have now imported the OpenAPI document into Postman.

Sending a request

First, you need to obtain a Control API token to authenticate any requests you send to the Control API.

For many Control API requests you also need to specify your account ID or app ID. You can see the account ID and app ID section for details on how to obtain these.

Now that you have obtained the token and IDs, you can learn how to send a request in Postman.

1. Expand the collection to the Lists account apps request. The following screenshot shows the parameters for the request:

2. The Lists account apps request is an account-level operation and therefore requires your account ID in the account_id path variable. This path variable is highlighted with the green box in the previous screenshot. Paste your Ably account ID into the VALUE field.

3. You also need to enter your Control API token as a Bearer Token in the Authorization tab. Paste your Ably Control API token into the token field marked with the placeholder text <Bearer Token>, as shown in the following screenshot:

Note: If you don't supply this token, your request will fail to authenticate.

4. Now that this request is configured, you can send the request by clicking the Send button:

5. The server returns a response, listing your Ably apps:

You can now try out other requests. You need to set the necessary parameters and authentication token as required by that specific request. Consult the API Reference for further information.