Ably: tokens are scoped by capability, publish needs publish on the channel

TL;DR

Because of least-privilege scoping, health checks should request a token rather than publishing to a test channel, since a valid subscribe-only key would fail the publish.

Steps

1. When Ably returns a 40160, check the token's capability map before debugging the connection: the token likely lacks the operation on that channel. Scope tokens to the minimum operations per channel pattern, and validate integrations with a token request rather than a publish, so a correctly scoped read-only key doesnt look broken.

When to use

You are seeing this: When Ably returns a 40160, check the token's capability map before debugging the connection: the token likely lacks the operation on that channel. Use this skill when you run into "Ably: tokens are scoped by capability, publish needs publish on the channel".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Source: Ably docs (capabilities reference): API keys and tokens carry capability operations per channel resource, such as subscribe, publish, presence, and history. A token scoped to subscribe-only fails publish attempts with a 40160 capability error. Because of least-privilege scoping, health checks should request a token rather than publishing to a test channel, since a valid subscribe-only key would fail the publish.

Verified resolution: When Ably returns a 40160, check the token's capability map before debugging the connection: the token likely lacks the operation on that channel. Scope tokens to the minimum operations per channel pattern, and validate integrations with a token request rather than a publish, so a correctly scoped read-only key doesnt look broken.

Source URL: https://github.com/ably/docs/blob/HEAD/src/pages/docs/auth/capabilities.mdx