Token authentication documentation clarity

[mclark-ably]

On https://ably.com/docs/api/rest-api#token-authentication we talk about an Ably-compatible token which covers an Ably token or an Ably JWT

Token Authentication uses an Ably-compatible token to authenticate with Ably without sharing a private API key. This can be an Ably Token obtained via the REST API requestToken endpoint, an Ably JWT signed by your API key, or an External JWT object with an embedded Ably-compatible token.

but then on https://ably.com/docs/auth/token?lang=javascript#embedded

If a system has an existing JWT scheme, it’s possible to embed an Ably Token as a claim within it. Where maybe it should also say an Ably-compatible token instead of Ably Token

Its not really clear that instead of embedding an Ably token (requiring a request to Ably) you can also embed an Ably JWT that is signed by the auth server

┆Issue is synchronized with this Jira Task by Unito

[mschristensen]

Just to add some more context on this:

1. We document how to construct your own JWT using your API key: https://ably.com/docs/auth/token?lang=javascript#standard
2. And we document how to embed and Ably Token in your own JWT under x-ably-token: https://ably.com/docs/auth/token?lang=javascript#embedded

But from the diagram in (2), it makes it look like the Ably Token must be retrieved from Ably servers. However this is not the only option, any valid token that can be used to authenticate with Ably can be included in x-ably-token, including one that you can construct yourself as documented in (1).

cc @paddybyers