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

Copied!

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

Copied!

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

Copied!

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

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

Using the access token

Copied!

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!

Obtain token details using the Control API

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!

Account ID and app ID

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.

How to find your account ID

Copied!

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

Copied!

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

Copied!

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

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 app you want to modify (see here)

Account

Copied!

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

To retrieve account-level statistics:


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

Copy
Copied!

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

Copy
Copied!

Apps

Copied!

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

Copied!

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

Copy
Copied!

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
}

Copy
Copied!

List apps

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!

Retrieve app statistics

Copied!

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

Copy
Copied!

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

Copy
Copied!

Queues

Copied!

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

Copied!

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

Copy
Copied!

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"
    },
    ...
]

Copy
Copied!

Create a queue

Copied!

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

Copy
Copied!

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

Copy
Copied!

Keys

Copied!

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

Copied!

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

Copy
Copied!

Sample response:


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

Copy
Copied!

Create a key

Copied!

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

Copy
Copied!

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
}

Copy
Copied!

Update a key

Copied!

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

Copy
Copied!

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
}

Copy
Copied!

Revoke a key

Copied!

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

Copy
Copied!

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

Rules

Copied!

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

Copied!

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

Copy
Copied!

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"
        }
    },
    ...
]

Copy
Copied!

List a rule by rule ID

Copied!


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

Copy
Copied!

The rule details are returned for the specified rule.

Create a rule

Copied!

The following example creates a rule with the following configuration

Parameter	Value	Description
`ruleType`	http	The type of rule, in this case a webhook rule
`requestMode`	single	Request mode can be single or batched
`channelFilter`	^my-channel.*	An optional regular expression that allows the rule to be applied to the specified channel set
`type`	channel.message	Source type. This means that the source event that will trigger this rule is any message on the channel
`url`	https://example.com/webhooks	The webhook endpoint. This is the URL triggered for the event
`format`	json	Format of encoding for the rule, in this case JSON
`name`	User-Agent	Optional header or headers, including custom headers that might be required. In this case a user agent header is specified (this needs to be set for some providers)
`value`	user-agent-name	The value of the header
`enveloped`	true	Wrap packet in metadata

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

Copy
Copied!

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

Copy
Copied!

This shows the created webhook rule.

Update a rule

Copied!

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

Copy
Copied!

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

Delete a rule

Copied!

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

Copy
Copied!

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

Testing with Postman

Copied!

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

Copied!

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:

Make sure you have Postman installed.

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

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

In the Import dialog, use the default settings and click “Import”:

The imported document now appears in your Postman collections:

You have now imported the OpenAPI document into Postman.

Sending a request

Copied!

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.

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

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.

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.

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

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.