> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ably/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication Overview

All interactions between a client and the Ably service must be authenticated.

## Recommended authentication

| Environment                         | Recommended Method                              | Details                                                                               |
| ----------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------- |
| Client-side (browsers, mobile apps) | [Token authentication](/docs/pubsub/auth/token) | Your server issues tokens (JWT recommended); clients use `authCallback` to fetch them |
| Server-side (Node.js, Python, etc.) | [Basic authentication](/docs/pubsub/auth/basic) | Use your API key directly in trusted environments                                     |

<Aside data-type="important">
  Never use API keys in client-side code (that is, code that is not running in a server, but a client device such as a mobile or web app). API keys don't expire; once compromised, they grant indefinite access. Use [token authentication](/docs/pubsub/auth/token) with tokens that have narrowly-scoped capabilities, are short-lived, and can be revoked.
</Aside>

## Ably API keys

Every Ably app can have one or more API keys associated with it. API keys authenticate directly with Ably or are used to issue tokens.

Keys can have different [capabilities](/docs/auth/capabilities), and tokens issued from a key can only request a subset of those capabilities.

### API key format

An Ably API key string has the following format: `I2E_JQ.OqUdfg:EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0`

The API key has three parts:

1. `I2E_JQ` - the public app ID
2. `OqUdfg` - the public key ID (`I2E_JQ.OqUdfg` together form the public API key ID)
3. `EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0` - the API key secret (never share this)

### Create an API key

API keys are created in the [Ably dashboard](https://ably.com/dashboard) or programmatically via the [Control API](/docs/platform/account/control-api).

To create an API key in the dashboard:

1. Click the **API Keys** tab in your [dashboard](https://ably.com/accounts/any/apps/any/app_keys).
2. Click **Create a new API key**.
3. Enter a name to identify the key.
4. Select the [capabilities](/docs/auth/capabilities) to apply.
5. Optionally enable [token revocation](/docs/auth/revocation).
6. Optionally restrict scope to specific channels or queues.

## Selecting an authentication mechanism

Ably supports two authentication mechanisms:

1. **[Token authentication](/docs/pubsub/auth/token)**: Short-lived Ably Tokens that expire and can be revoked. Recommended for clients. Use JWTs for most applications, or native Ably Tokens when JWTs aren't suitable.
2. **[Basic authentication](/docs/pubsub/auth/basic)**: Uses your API key directly. Use only on trusted servers.

When deciding which method to use, apply the principle of least privilege: a client should only possess the credentials and rights it needs. If credentials are compromised, the damage is minimized.

Many applications use a mixed strategy: trusted servers use basic authentication to issue tokens, while browsers and devices use those tokens.

| Scenario                             | Recommended       | Details                                                   |
| ------------------------------------ | ----------------- | --------------------------------------------------------- |
| Client-side (browsers, mobile)       | JWT               | Use JWT authentication. No Ably SDK needed on your server |
| Server-side (trusted environment)    | Basic auth        | Use your API key directly                                 |
| Fine-grained per-user access control | JWT or Ably Token | Set capabilities per token                                |
| Time-limited or revocable access     | JWT or Ably Token | Tokens expire and can be revoked                          |
| Users must be identified             | JWT or Ably Token | Set `clientId` server-side                                |

## Next steps

* Learn about [basic authentication](/docs/pubsub/auth/basic)
* Learn about [token authentication](/docs/pubsub/auth/token)
* Understand [capabilities](/docs/auth/capabilities) for access control