diff --git a/src/data/nav/platform.ts b/src/data/nav/platform.ts index 8e1df1417d..a86cd77ee8 100644 --- a/src/data/nav/platform.ts +++ b/src/data/nav/platform.ts @@ -272,8 +272,8 @@ export default { index: true, }, { - name: 'User management', - link: '/docs/platform/account/users', + name: 'Team', + link: '/docs/platform/account/team', }, { name: 'Organizations', @@ -300,28 +300,70 @@ export default { index: true, }, { - name: 'Stats', - link: '/docs/platform/account/app/stats', - }, - { - name: 'API keys', - link: '/docs/platform/account/app/api', + name: 'Products', + pages: [ + { + name: 'Pub/Sub', + link: '/docs/platform/account/app/products/pubsub', + }, + { + name: 'Chat', + link: '/docs/platform/account/app/products/chat', + }, + { + name: 'Spaces', + link: '/docs/platform/account/app/products/spaces', + }, + { + name: 'LiveObjects', + link: '/docs/platform/account/app/products/liveobjects', + }, + { + name: 'LiveSync', + link: '/docs/platform/account/app/products/livesync', + }, + { + name: 'Push notifications', + link: '/docs/platform/account/app/products/push-notifications', + }, + ], + }, + { + name: 'Connections', + link: '/docs/platform/account/app/connections', }, { name: 'Queues', link: '/docs/platform/account/app/queues', }, { - name: 'Notifications', - link: '/docs/platform/account/app/notifications', - }, - { - name: 'Dev console', - link: '/docs/platform/account/app/console', - }, - { - name: 'Settings', - link: '/docs/platform/account/app/settings', + name: 'Monitoring', + link: '/docs/platform/account/app/monitoring', + }, + { + name: 'Configuration', + pages: [ + { + name: 'API keys', + link: '/docs/platform/account/app/configuration/api-keys', + }, + { + name: 'Rules', + link: '/docs/platform/account/app/configuration/rules', + }, + { + name: 'Integrations', + link: '/docs/platform/account/app/configuration/integrations', + }, + { + name: 'Application settings', + link: '/docs/platform/account/app/configuration/settings', + }, + ], + }, + { + name: 'Web client', + link: '/docs/platform/account/app/client', }, ], }, diff --git a/src/images/content/screenshots/control-api/account-settings-menu-item.png b/src/images/content/screenshots/control-api/account-settings-menu-item.png deleted file mode 100644 index f770793674..0000000000 Binary files a/src/images/content/screenshots/control-api/account-settings-menu-item.png and /dev/null differ diff --git a/src/images/content/screenshots/control-api/my-access-tokens-menu-item.png b/src/images/content/screenshots/control-api/my-access-tokens-menu-item.png deleted file mode 100644 index 76e440c8c8..0000000000 Binary files a/src/images/content/screenshots/control-api/my-access-tokens-menu-item.png and /dev/null differ diff --git a/src/images/content/screenshots/dash/access-token-set.png b/src/images/content/screenshots/dash/access-token-set.png new file mode 100644 index 0000000000..4f55a5b8be Binary files /dev/null and b/src/images/content/screenshots/dash/access-token-set.png differ diff --git a/src/images/content/screenshots/dash/access-token.png b/src/images/content/screenshots/dash/access-token.png new file mode 100644 index 0000000000..5ece95e3bc Binary files /dev/null and b/src/images/content/screenshots/dash/access-token.png differ diff --git a/src/images/content/screenshots/dash/account.png b/src/images/content/screenshots/dash/account.png deleted file mode 100644 index 138c5db320..0000000000 Binary files a/src/images/content/screenshots/dash/account.png and /dev/null differ diff --git a/src/images/content/screenshots/dash/app-settings.png b/src/images/content/screenshots/dash/app-settings.png new file mode 100644 index 0000000000..95e7269a86 Binary files /dev/null and b/src/images/content/screenshots/dash/app-settings.png differ diff --git a/src/images/content/screenshots/dash/apps1.png b/src/images/content/screenshots/dash/apps1.png new file mode 100644 index 0000000000..e35a00ec28 Binary files /dev/null and b/src/images/content/screenshots/dash/apps1.png differ diff --git a/src/images/content/screenshots/dash/channels1.png b/src/images/content/screenshots/dash/channels1.png new file mode 100644 index 0000000000..e7f7b3f78e Binary files /dev/null and b/src/images/content/screenshots/dash/channels1.png differ diff --git a/src/images/content/screenshots/dash/cli.png b/src/images/content/screenshots/dash/cli.png new file mode 100644 index 0000000000..70d07d4eef Binary files /dev/null and b/src/images/content/screenshots/dash/cli.png differ diff --git a/src/images/content/screenshots/dash/connections.png b/src/images/content/screenshots/dash/connections.png new file mode 100644 index 0000000000..4cc8427bea Binary files /dev/null and b/src/images/content/screenshots/dash/connections.png differ diff --git a/src/images/content/screenshots/dash/create-app.png b/src/images/content/screenshots/dash/create-app.png deleted file mode 100644 index acb9cea59b..0000000000 Binary files a/src/images/content/screenshots/dash/create-app.png and /dev/null differ diff --git a/src/images/content/screenshots/dash/dash-tabs.png b/src/images/content/screenshots/dash/dash-tabs.png deleted file mode 100644 index 48b3a570e2..0000000000 Binary files a/src/images/content/screenshots/dash/dash-tabs.png and /dev/null differ diff --git a/src/images/content/screenshots/dash/global.png b/src/images/content/screenshots/dash/global.png new file mode 100644 index 0000000000..4bd1e01a42 Binary files /dev/null and b/src/images/content/screenshots/dash/global.png differ diff --git a/src/images/content/screenshots/dash/integration.png b/src/images/content/screenshots/dash/integration.png new file mode 100644 index 0000000000..2e818b5e00 Binary files /dev/null and b/src/images/content/screenshots/dash/integration.png differ diff --git a/src/images/content/screenshots/dash/keys.png b/src/images/content/screenshots/dash/keys.png new file mode 100644 index 0000000000..106cfa4cbc Binary files /dev/null and b/src/images/content/screenshots/dash/keys.png differ diff --git a/src/images/content/screenshots/dash/log1.png b/src/images/content/screenshots/dash/log1.png new file mode 100644 index 0000000000..d4fd41ae17 Binary files /dev/null and b/src/images/content/screenshots/dash/log1.png differ diff --git a/src/images/content/screenshots/dash/overview.png b/src/images/content/screenshots/dash/overview.png new file mode 100644 index 0000000000..d0cedcae1e Binary files /dev/null and b/src/images/content/screenshots/dash/overview.png differ diff --git a/src/images/content/screenshots/dash/programmatic-man.png b/src/images/content/screenshots/dash/programmatic-man.png new file mode 100644 index 0000000000..7de103fa7c Binary files /dev/null and b/src/images/content/screenshots/dash/programmatic-man.png differ diff --git a/src/images/content/screenshots/dash/push.png b/src/images/content/screenshots/dash/push.png new file mode 100644 index 0000000000..5d38897d49 Binary files /dev/null and b/src/images/content/screenshots/dash/push.png differ diff --git a/src/images/content/screenshots/dash/queues.png b/src/images/content/screenshots/dash/queues.png new file mode 100644 index 0000000000..c5257e3460 Binary files /dev/null and b/src/images/content/screenshots/dash/queues.png differ diff --git a/src/images/content/screenshots/dash/rules.png b/src/images/content/screenshots/dash/rules.png new file mode 100644 index 0000000000..8754fe743a Binary files /dev/null and b/src/images/content/screenshots/dash/rules.png differ diff --git a/src/images/content/screenshots/dash/spaces1.png b/src/images/content/screenshots/dash/spaces1.png new file mode 100644 index 0000000000..4fa448b46d Binary files /dev/null and b/src/images/content/screenshots/dash/spaces1.png differ diff --git a/src/images/content/screenshots/dash/stats-chart.png b/src/images/content/screenshots/dash/stats-chart.png deleted file mode 100644 index ddf94f80d7..0000000000 Binary files a/src/images/content/screenshots/dash/stats-chart.png and /dev/null differ diff --git a/src/images/content/screenshots/dash/stats-table.png b/src/images/content/screenshots/dash/stats-table.png deleted file mode 100644 index b1953086cf..0000000000 Binary files a/src/images/content/screenshots/dash/stats-table.png and /dev/null differ diff --git a/src/images/content/screenshots/dash/team.png b/src/images/content/screenshots/dash/team.png new file mode 100644 index 0000000000..19533aaf08 Binary files /dev/null and b/src/images/content/screenshots/dash/team.png differ diff --git a/src/images/content/screenshots/dash/web-client.png b/src/images/content/screenshots/dash/web-client.png new file mode 100644 index 0000000000..f0ca2c01b2 Binary files /dev/null and b/src/images/content/screenshots/dash/web-client.png differ diff --git a/src/images/content/screenshots/dash/your-apps.png b/src/images/content/screenshots/dash/your-apps.png deleted file mode 100644 index 94576b4fa0..0000000000 Binary files a/src/images/content/screenshots/dash/your-apps.png and /dev/null differ diff --git a/src/pages/docs/auth/token.mdx b/src/pages/docs/auth/token.mdx new file mode 100644 index 0000000000..4201055487 --- /dev/null +++ b/src/pages/docs/auth/token.mdx @@ -0,0 +1,1140 @@ +--- +title: "Token auth" +meta_description: "Token authentication allows clients to authenticate with Ably, without exposing the Ably API key and secret." +--- + +Token authentication uses a trusted device with an [API key](/docs/auth#api-key) to issue time-limited tokens to untrusted clients. Tokens have a limited set of access rights, known as [capabilities](/docs/auth/capabilities), and can have a specific [identity](/docs/auth/identified-clients) using a `clientId`. + +Token authentication is the recommended authentication method to use client-side as it provides more fine-grained access control and limits the risk of credentials being exposed. + +## Access restrictions + +### Token-based client validation + +Token authentication enables you to validate client characteristics (such as origin, IP address, cookies, or any other client features) in your authentication server before issuing tokens. This provides flexible access control as you can implement any validation logic in your auth server as part of the token issuance process. + +### API key restrictions + +For cases where token authentication is impractical, Ably can add origin or IP address restrictions directly to API keys. However, this approach has significant limitations: + +- Less flexible than token authentication. +- Manual intervention required to modify restrictions. +- Enterprise support packages only: contact [Ably support](https://ably.com/support) if interested. +- Not a security boundary: origin headers can be easily spoofed, especially outside browser contexts. +- Permissive fallback: requests with no origin header are allowed when origin restrictions are set. + +For maximum security and flexibility, token authentication with server-side validation is the recommended approach. + +Any of the following cause an SDK to use token authentication: + +* An [`authUrl`](/docs/api/realtime-sdk/types#client-options) or [`authCallback`](/docs/api/realtime-sdk/types#client-options) is provided that returns an Ably-compatible token or an Ably [`TokenRequest`](/docs/api/realtime-sdk/types#token-request). +* [`useTokenAuth`](/docs/api/realtime-sdk/types#client-options) is true. +* A [`token`](/docs/api/realtime-sdk/types#client-options) or [`tokenDetails`](/docs/api/realtime-sdk/types#client-options) property is provided. + +Providing a literal `token` or `tokenDetails` is typically used for testing: since tokens are short-lived, in production you typically want to use an authentication method that allows the client library to renew the token automatically before the current token expires. + +Authentication using tokens can be achieved requesting and issuing [Ably Tokens](#tokens) or passing a [JSON Web Tokens (JWT)](#jwt) to the Ably service. + +## Token refresh + +One of the important benefits of using an Ably SDK is that the automatic refresh of tokens will be handled for you. + +To use automatic refresh of tokens, provide either an `authUrl` or an `authCallback`. When the token is near to expiry the `authUrl` or `authCallback` is invoked and a new token is automatically requested. + +### Token authentication workflow + +Understanding how token authentication works helps clarify why automatic renewal is essential: + +1. Your server uses the Ably API key to request a 'Token Request' object from Ably. +2. Your client uses this 'Token Request' object to request the actual token from the Ably server every time it needs to authenticate. +3. These tokens are short-lived and expire after a certain period of time. +4. The client SDK automatically requests a new token just before the previous one expires, ensuring the connection never drops due to authentication failure. + +Using an `authUrl` or `authCallback` ensures your client automatically requests a new token when needed, making the authentication process seamless and preventing service interruptions. + +An `authURL` is recommended for use with web-based clients as they can easily utilize cookies and other web-only features. For non-web clients, `authCallback` is the recommended strategy. + +### Token TTL limits + +Ably enforces maximum TTL (time-to-live) limits on different types of tokens: + +- Access tokens: Maximum TTL of 24 hours. +- Device tokens (for push notifications): Maximum TTL of 5 years. +- Revocable tokens: Maximum TTL of 1 hour (when [token revocation](/docs/auth/revocation#revocable-tokens) is enabled). + + + +### authUrl + +You can specify an `authUrl` when you create the Ably client. For example: + + +```realtime_javascript +const realtime = new Ably.Realtime({ authUrl: '/auth' }); +``` + +```realtime_nodejs +const realtime = new Ably.Realtime({ authUrl: '/auth' }); +``` + +```realtime_ruby +realtime = Ably::Realtime.new(auth_url: '/auth') +``` + +```realtime_python + realtime = AblyRealtime(auth_url='/auth') +``` + +```realtime_java +ClientOptions options = new ClientOptions(); +options.authUrl = "/auth"; +AblyRealtime realtime = new AblyRealtime(options); +``` + +```realtime_objc +ARTClientOptions *options = [[ARTClientOptions alloc] init]; +options.authUrl = [NSURL URLWithString:@"/auth"]; +ARTRealtime *realtime = [[ARTRealtime alloc] initWithOptions:options]; +``` + +```realtime_swift +let options = ARTClientOptions() +options.authUrl = NSURL(string: "/auth") +let realtime = ARTRealtime(options: options) +``` + +```realtime_csharp +ClientOptions options = new ClientOptions(); +options.AuthUrl = new Uri("/auth"); +AblyRealtime realtime = new AblyRealtime(options); +``` + +```realtime_go +client, err := ably.NewRealtime(ably.WithAuthURL("/auth")) +``` + +```realtime_flutter +final clientOptions = ably.ClientOptions( + authUrl: '/auth' +); +final realtime = ably.Realtime(options: clientOptions); +``` + +```rest_javascript + const rest = new Ably.Rest({ authUrl: '/auth' }); +``` + +```rest_nodejs + const rest = new Ably.Rest({ authUrl: '/auth' }); +``` + +```rest_ruby + rest = Ably::Rest.new(auth_url: '/auth') +``` + +```rest_python + rest = AblyRest(auth_url='/auth') +``` + +```rest_php + $rest = new Ably\AblyRest(['authUrl' => '/auth']); +``` + +```rest_java + ClientOptions options = new ClientOptions(); + options.authUrl = "/auth"; + AblyRest rest = new AblyRest(options); +``` + +```rest_csharp + AblyRest rest = new AblyRest(new ClientOptions { AuthUrl = new Uri("/auth") }); +``` + +```rest_objc + ARTClientOptions *options = [[ARTClientOptions alloc] init]; + options.authUrl = [NSURL URLWithString:@"/auth"]; + ARTRest *rest = [[ARTRest alloc] initWithOptions:options]; +``` + +```rest_swift + let options = ARTClientOptions() + options.authUrl = NSURL(string: "/auth") + let rest = ARTRest(options: options) +``` + +```rest_go + client, err := ably.NewREST(ably.WithAuthURL("/auth")) +``` + +```rest_flutter +final clientOptions = ably.ClientOptions( + authUrl: '/auth' +); +final rest = ably.Rest(options: clientOptions); +``` + + +The client will obtain a token, JWT, or tokenRequest from the URL and use it to authenticate requests to Ably. Before token expiry, a request for a new token will be made automatically by the client to the `authUrl`. + +### authCallback + +You can specify an authentication callback function when you create the Ably client. Inside `authCallback`, you can make a network request to your servers to generate the `tokenRequest`. For example: + + +```realtime_javascript +const ablyClient = new Realtime({ + authCallback: async (tokenParams, callback) => { + let tokenRequest; + try { + tokenRequest = await obtainTokenRequest(); // Make a network request to your server + } catch (err) { + callback(err, null); + return; + } + callback(null, tokenRequest); + } +}); +``` + +```realtime_nodejs +const ablyClient = new Realtime({ + authCallback: async (tokenParams, callback) => { + let tokenRequest; + try { + tokenRequest = await obtainTokenRequest(); // Make a network request to your server + } catch (err) { + callback(err, null); + return; + } + callback(null, tokenRequest); + } +}); +``` + +```realtime_python +realtime = AblyRealtime(auth_callback=get_token_request) + +async def get_token_request(*args, **kwargs): + create_token_request = await get_token_request() // Implement this function to get a token request from your server + + if create_token_request.status_code == 200: + token_request = create_token_request.json() + + return token_request + else: + raise Exception(f"Failed to retrieve token request: {create_token_request.status_code} - {create_token_request.text}") +``` + +```realtime_go +realtime, _ := ably.NewRealtime( + ably.WithAuthCallback(func(context.Context, ably.TokenParams) (ably.Tokener, error) { + createTokenRequest := getTokenRequest() // Implement this function to get a token request from your server + + if (createTokenRequest.StatusCode == 200) { + return createTokenRequest + } + + return "Failed to retrieve token request: '%v' - '%v'", createTokenRequest.StatusCode, createTokenRequest.Text + }) +) +``` + +```realtime_flutter +ably.ClientOptions clientOptions = ably.ClientOptions( + authCallback: (ably.TokenParams tokenParams) async { + // `createTokenRequest` should be implemented to communicate with user server + ably.TokenRequest tokenRequest = await createTokenRequest(tokenParams); + // `authCallback` has to return an instance of TokenRequest + return tokenRequest; + } +); + +ably.Realtime realtime = ably.Realtime(options: clientOptions); +``` + +```realtime_java +ClientOptions options = new ClientOptions(); + +options.authCallback = new Auth.TokenCallback() { + @Override + public Object getTokenRequest(Auth.TokenParams params) throws AblyException { + // Implement this function to get a token request from your server + return getTokenRequestFromServer(); + } +}; + +AblyRealtime realtime = new AblyRealtime(options); +``` + +```rest_javascript +const rest = new Ably.Rest({ + authCallback: (tokenParams, callback) => { + // implement your callback here + }, +}); +``` + +```rest_nodejs +const rest = new Ably.Rest({ + authCallback: (tokenParams, callback) => { + // implement your callback here + }, +}); +``` + +```rest_python +rest = AblyRest(auth_callback=get_token_request) + +async def get_token_request(*args, **kwargs): + create_token_request = await get_token_request() // Implement this function to get a token request from your server + + if create_token_request.status_code == 200: + token_request = create_token_request.json() + + return token_request + else: + raise Exception(f"Failed to retrieve token request: {create_token_request.status_code} - {create_token_request.text}") +``` + +```rest_java +ClientOptions options = new ClientOptions(); + +options.authCallback = new Auth.TokenCallback() { + @Override + public Object getTokenRequest(Auth.TokenParams params) throws AblyException { + // Implement this function to get a token request from your server + return getTokenRequestFromServer(); + } +}; + +AblyRest rest = new AblyRest(options); +``` + +```rest_php +$rest = new Ably\AblyRest( + [ + 'authCallback' => function(Ably\Models\TokenParams $params) { + $curl = curl_init('/auth'); + curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); + $response = curl_exec($curl); + curl_close($curl); + + $tokenRequestData = json_decode($response, true); + $tokenRequest = new Ably\Models\TokenRequest($tokenRequestData); + + return $tokenRequest; + } + ] +); +``` + +```rest_go +rest, _ := ably.NewREST( + ably.WithAuthCallback(func(context.Context, ably.TokenParams) (ably.Tokener, error) { + createTokenRequest := getTokenRequest() // Implement this function to get a token request from your server + + if (createTokenRequest.StatusCode == 200) { + return createTokenRequest + } + + return "Failed to retrieve token request: '%v' - '%v'", createTokenRequest.StatusCode, createTokenRequest.Text + }) +) +``` + +```rest_flutter +ably.ClientOptions clientOptions = ably.ClientOptions( + authCallback: (ably.TokenParams tokenParams) async { + // `createTokenRequest` should be implemented to communicate with user server + ably.TokenRequest tokenRequest = await createTokenRequest(tokenParams); + // `authCallback` has to return an instance of TokenRequest + return tokenRequest; + } +); + +ably.Rest rest = ably.Rest(options: clientOptions); +``` + + +The [`tokenParams`](/docs/api/realtime-sdk/authentication#token-params) argument in `authCallback` is available for convenience, allowing you to see the capabilities, `clientId`, and other details requested by the client. However, `tokenParams` should not be trusted or used to generate the `tokenRequest` on the server side. Instead it is recommended that your `createTokenRequest` API authenticates clients separately, for example based on cookies, headers, or HTTP body. + +## AuthOptions + +Use properties set with [`AuthOptions`](/docs/api/realtime-sdk/authentication#auth-options) to override the default authentication values set when instantiating a client. You can also embed `AuthOptions` into your [`ClientOptions`](/docs/api/realtime-sdk#client-options) while instantiating. + +There are several `AuthOptions` you can specify along with `authUrl` and `authCallback`: + +- `authMethod` :- when `authUrl` is called, the default `GET` method will be used, unless `POST` is specified. +- `authHeaders` :- allows you to pass additional headers as required, depending on your use case. +- `authParams` :- allows you to pass additional query parameters, depending on your use case. + +The following is an example of passing `AuthOptions`: + + +```realtime_javascript +const realtime = new Ably.Realtime({ + authUrl: "/auth", + authMethod: "POST", + authParams: {p1: param1, b: param2}, + authHeaders: {h1: header1, h2: header2} +}); +``` + +```realtime_nodejs +const realtime = new Ably.Realtime({ + authUrl: "/auth", + authMethod: "POST", + authParams: {p1: param1, b: param2}, + authHeaders: {h1: header1, h2: header2} +}); +``` + +```realtime_python +realtime = AblyRealtime(auth_url='/auth', + auth_method="GET", + auth_headers={'h1': 'v1'}, + auth_params={'param1': 'param2'}) +``` + +```realtime_go +headers := http.Header{} +headers.Set("h1", "header1") +headers.Set("h2", "header2") + +client, err := ably.NewRealtime( + ably.WithAuthURL("/auth"), + ably.WithAuthMethod("GET"), + ably.WithAuthHeaders(headers), + ably.WithAuthParams(url.Values{ + "p1": {"param1"}, + "p2": {"param2"}, + })) +if err != nil { + panic(err) +} +``` + +```realtime_flutter +final clientOptions = ably.ClientOptions( + authUrl: '/auth', + authMethod: 'GET', + authParams: { + 'p1': 'param1', + 'b': 'param2', + }, + authHeaders: { + 'h1': 'header1', + 'h2': 'header2', + }, +); +final realtime = ably.Realtime(options: clientOptions); +``` + +```realtime_java +ClientOptions options = new ClientOptions(); +options.authUrl = "/auth"; +options.authMethod = "POST"; +options.authParams = new Param[]{ + new Param("p1", "param1"), + new Param("p2", "param2") +}; +options.authHeaders = new Param[]{ + new Param("h1", "header1"), + new Param("h2", "header2") +}; + +AblyRealtime realtime = new AblyRealtime(options); +``` + +```rest_javascript +const rest = new Ably.Rest({ + authUrl: "/auth", + authMethod: "POST", + authParams: {p1: param1, b: param2}, + authHeaders: {h1: header1, h2: header2} +}); +``` + +```rest_nodejs +const rest = new Ably.Rest({ + authUrl: "/auth", + authMethod: "POST", + authParams: {p1: param1, b: param2}, + authHeaders: {h1: header1, h2: header2} +}); +``` + +```rest_python +rest = AblyRest(auth_url='/auth', + auth_method="GET", + auth_headers={'h1': 'v1'}, + auth_params={'param1': 'param2'}) +``` + +```rest_go +headers := http.Header{} +headers.Set("h1", "header1") +headers.Set("h2", "header2") + +client, err := ably.NewREST( + ably.WithAuthURL("/auth"), + ably.WithAuthMethod("GET"), + ably.WithAuthHeaders(headers), + ably.WithAuthParams(url.Values{ + "p1": {"param1"}, + "p2": {"param2"}, + })) +if err != nil { + panic(err) +} +``` + +```rest_flutter +final clientOptions = ably.ClientOptions( + authUrl: '/auth', + authMethod: 'GET', + authParams: { + 'p1': 'param1', + 'b': 'param2', + }, + authHeaders: { + 'h1': 'header1', + 'h2': 'header2', + }, +); +final rest = ably.Rest(options: clientOptions); +``` + +```rest_java +ClientOptions options = new ClientOptions(); +options.authUrl = "/auth"; +options.authMethod = "POST"; +options.authParams = new Param[]{ + new Param("p1", "param1"), + new Param("p2", "param2") +}; +options.authHeaders = new Param[]{ + new Param("h1", "header1"), + new Param("h2", "header2") +}; + +AblyRest rest = new AblyRest(options); +``` + + +## Ably Tokens + +Ably Tokens can be used to authenticate with Ably in the following ways: + +* Ably [TokenRequest](#token-request) is created by your servers and passed to clients. +* An [Ably Token](#ably-token) is issued by your servers and passed to clients. + +Note that the machine on which you are running your auth server should have an accurate clock, as tokens and `TokenRequest` contain a timestamp. You can use an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd), or if you are not able to control your server's clock, you can wish to use the `queryTime` [auth option](/docs/api/rest-sdk/types#auth-options). + +### Ably TokenRequest + +Using an Ably SDK, a `TokenRequest` is [generated from your server](/docs/api/realtime-sdk/authentication#create-token-request) and returned to the client-side SDK instance. The client-side SDK instance then uses the [`TokenRequest`](/docs/api/realtime-sdk/types#token-request) to request an [Ably Token](/docs/api/realtime-sdk/authentication#request-token) from Ably, and subsequently authenticates using that [Ably Token](/docs/api/realtime-sdk/authentication#token-details). + +This is the recommended approach for client-side authentication, for the following reasons: + +* An Ably `TokenRequest` can be generated securely by your servers without communicating with Ably. +* Your secret API key is never shared with Ably or your clients. +* An Ably `TokenRequest` cannot be tampered with due to being signed, must be used soon after creation, and can only be used once. + +The process used by Ably SDKs to authenticate with Ably using a `TokenRequest` is illustrated in the following diagram: + +![Ably TokenRequest auth process diagram](../../../images/content/diagrams/Ably-token-auth-1.png) + +The following is an example of creating an Ably `TokenRequest`: + + +```javascript +const ably = new Ably.Rest({ key: '{{API_KEY}}' }); +const tokenRequest = await ably.auth.createTokenRequest({ clientId: 'client@example.com' }); +``` + +```python +ably = AblyRest('{{API_KEY}}') +token = await ably.auth.create_token_request( +{ + "clientId": "client@example.com", + "capability": { + "channel1": ["publish", "subscribe"], + }, + 'ttl': 3600 * 1000, # ms +}) +``` + +```java +ClientOptions options = new ClientOptions("{{API_KEY}}"); +AblyRest rest = new AblyRest(options); + +Auth.TokenParams tokenParams = new Auth.TokenParams(); +tokenParams.clientId = "client@example.com"; + +Auth.TokenRequest tokenDetails = rest.auth.createTokenRequest(tokenParams, null); +``` + +```php +$rest = new Ably\AblyRest( + ['key' => '{{API_KEY}}'] +); + +$tokenRequest = $rest->auth->createTokenRequest( + ['clientId' => 'client@example.com'] +); +``` + +```go +rest, err := ably.NewREST( + ably.WithKey("{{API_KEY}}")) +if err != nil { + log.Fatalf("Error creating Ably client: %v", err) +} + +tokenParams := &ably.TokenParams{ClientID: "client@example.com"} +tokenRequest, _ := rest.Auth.CreateTokenRequest(tokenParams) +``` + +```flutter +final clientOptions = ably.ClientOptions( + key: '{{API_KEY}}', +); +final rest = ably.Rest(options: clientOptions); +const tokenParams = ably.TokenParams( + clientId: 'client@example.com' +); +final tokenRequest = rest.auth.createTokenRequest(tokenParams: tokenParams); +``` + + +Clients can pass this server-side generated `TokenRequest` to Ably to authenticate with Ably automatically. + +### Ably Token + +Using an Ably SDK, an Ably Token is [requested by your servers](/docs/api/realtime-sdk/authentication#request-token) from Ably and then passed to the client-side SDK instance. The client-side SDK instance then uses that [Ably Token](/docs/api/realtime-sdk/authentication#tokens) to authenticate with Ably. This is an alternative approach for authentication that enables you to issue"Ably Tokens directly as opposed to providing Ably `TokenRequests` from your servers. + +The advantage for clients is that it saves one round trip request as they do not need to request an Ably Token themselves. The disadvantage is that your servers must communicate with Ably each time an Ably Token is required. + +The process used by Ably SDKs to authenticate with Ably using an Ably Token is illustrated in the following diagram: + +![Ably token auth process diagram](../../../images/content/diagrams/Ably-Auth-Overview1.png) + +The following is an example of issuing an Ably Token from a server: + + +```javascript +const ably = new Ably.Rest({ key: '{{API_KEY}}' }); +const tokenDetails = await ably.auth.requestToken({ clientId: 'client@example.com' }); +``` + +```python +rest = AblyRest(key='{{API_KEY}}') +token_request_params = { + 'clientId': 'client@example.com', +} + +token_details = await rest.auth.request_token(token_params=token_request_params) +``` + +```java +ClientOptions options = new ClientOptions("{{API_KEY}}"); +AblyRest rest = new AblyRest(options); + +Auth.TokenParams tokenParams = new Auth.TokenParams(); +tokenParams.clientId = "client@example.com"; + +Auth.TokenDetails tokenDetails = rest.auth.requestToken(tokenParams, null); +``` + +```php +$rest = new Ably\AblyRest( + ['key' => '{{API_KEY}}'] +); + +$tokenDetails = $rest->auth->requestToken( + ['clientId' => 'client@example.com'] +); +``` + +```go +rest, err := ably.NewREST( + ably.WithKey("API_KEY")) +if err != nil { + log.Fatalf("Error creating Ably client: %v", err) +} + +tokenParams := &ably.TokenParams{ClientID: "client@example.com"} +tokenRequest, _ := rest.Auth.RequestToken(context.Background(), tokenParams) +``` + +```flutter +final clientOptions = ably.ClientOptions( + key: '{{API_KEY}}', +); +final rest = ably.Rest(options: clientOptions); + +const tokenParams = ably.TokenParams( + clientId: 'client@example.com', +); +final tokenDetails = await rest.auth.requestToken( + tokenParams: tokenParams +); +``` + + +## JSON Web Tokens (JWT) + +JSON Web Tokens (JWT) can be used to authenticate with Ably in the following ways: + +* [Ably JWT](#standard) is created by your servers and passed to clients. +* [Ably Token](#embedded) is embedded in a JWT from your server and passed to clients. + +Note that the machine on which you are running your auth server should have an accurate clock, as tokens contain a timestamp. You can use an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd), or if you are not able to control your server's clock, you can wish to use the `queryTime` [auth option](/docs/api/rest-sdk/types#auth-options). + +### JWT using your API key + +It is possible to use a [JWT](https://jwt.io) as a form of token for authentication with Ably, so long as it is structured appropriately, in what will be referred to as an [Ably JWT](/docs/api/realtime-sdk/authentication#ably-jwt). It is possible for an Ably JWT to contain claims indicating its `clientId`, capabilities and expiry - in an analogous way to an [Ably Token](#tokens) - and it is signed with the applicable [Ably API key's secret part](/docs/auth#api-key). + +This is similar to signing an Ably [`TokenRequest`](#token-request), but the client does not need to request an Ably Token, instead being able to use the Ably JWT as a token in itself. Any compliant third-party JWT library may be used to create the JWT without requiring the token to be issued by Ably. This can be useful for situations where an Ably client library is not available, such as an embedded device connecting to Ably via [MQTT](/docs/protocols/mqtt). + +The process used by Ably SDKs to authenticate with Ably using JWTs is illustrated in the following diagram: + +![Ably JWT auth method](../../../images/content/diagrams/Ably-Auth-Overview2.png) + +The following is an example of creating an Ably JWT: + + +To generate a JWT token in Flutter, you will need to install the [`crypto`](https://pub.dev/packages/crypto) library + + + +To generate a JWT token in Java, you will need to install the [`java-jwt`](https://github.com/auth0/java-jwt) library. + + + +```javascript + var header = { + "typ":"JWT", + "alg":"HS256", + "kid": "{{API_KEY_NAME}}" + } + var currentTime = Math.round(Date.now()/1000); + var claims = { + "iat": currentTime, /* current time in seconds */ + "exp": currentTime + 3600, /* time of expiration in seconds */ + "x-ably-capability": "{\"*\":[\"*\"]}" + } + var base64Header = btoa(header); + var base64Claims = btoa(claims); + /* Apply the hash specified in the header */ + var signature = hash((base64Header + "." + base64Claims), "{{API_KEY_SECRET}}"); + var ablyJwt = base64Header + "." + base64Claims + "." + signature; +``` + +```python + import jwt + import time + + def createAblyJwt(ably_api_key: str): + # Split the API key into key ID and secret + parts = ably_api_key.split(":") + kid = parts[0] + + # Prepare JWT headers + headers = { + "typ": "JWT", + "alg": "HS256", + "kid": kid + } + + # Prepare JWT claims + claims = { + "iat": int(time.time()), # Issued at time + "exp": int(time.time()) + 120, # Expiration time (2 minutes from now) + "x-ably-capability": "{\"*\":[\"*\"]}" # Full capability + } + + # Encode the JWT + jwtToken = jwt.encode(headers=headers, payload=claims, key=parts[1]) + return jwtToken +``` + +```java +Map headerClaims = new HashMap<>(); +headerClaims.put("typ", "JWT"); +headerClaims.put("alg", "HS256"); +headerClaims.put("kid", "{{API_KEY_NAME}}"); + +// Define the current time +long currentTimeInSeconds = System.currentTimeMillis() / 1000; + +// Define the claims +Map claims = new HashMap<>(); +claims.put("iat", currentTimeInSeconds); +claims.put("exp", currentTimeInSeconds + 3600); +claims.put("x-ably-capability", "{\"*\":[\"*\"]}"); + +// Create the JWT +Algorithm algorithm = Algorithm.HMAC256("{{API_KEY_SECRET}}"); +String token = JWT.create() + .withHeader(headerClaims) + .withPayload(claims) + .sign(algorithm); +``` + +```php +$header = [ + 'typ' => 'JWT', + 'alg' => 'HS256', + 'kid' => '{{API_KEY_NAME}}' +]; +$currentTime = time(); +$claims = [ + 'iat' => $currentTime, /* current time in seconds */ + 'exp' => $currentTime + 3600, /* time of expiration in seconds (an hour) */ + 'x-ably-capability' => '{\"*\":[\"*\"]}' +]; +$base64Header = base64_encode(json_encode($header)); +$base64Claims = base64_encode(json_encode($claims)); +$signature = hash_hmac( + 'sha256', + $base64Header . '.' . $base64Claims, + '{{API_KEY_SECRET}}', + true +); +$jwt = $base64Header . '.' . $base64Claims . '.' . $signature; +``` + +```go + // Create JWT header + header := map[string]string{ + "typ": "JWT", + "alg": "HS256", + "kid": "{{API_KEY_NAME}}", + } + + // Get current time in seconds + currentTime := time.Now().Unix() + + // Create JWT claims + claims := map[string]interface{}{ + "iat": currentTime, // current time in seconds + "exp": currentTime + 3600, // time of expiration in seconds + "x-ably-capability": "{\"*\":[\"*\"]}", + } + + // Encode header to base64 + headerJSON, err := json.Marshal(header) + if err != nil { + log.Fatalf("Failed to marshal header: %v", err) + } + base64Header := base64.RawURLEncoding.EncodeToString(headerJSON) + + // Encode claims to base64 + claimsJSON, err := json.Marshal(claims) + if err != nil { + log.Fatalf("Failed to marshal claims: %v", err) + } + base64Claims := base64.RawURLEncoding.EncodeToString(claimsJSON) + + // Create the signature + dataToSign := base64Header + "." + base64Claims + h := hmac.New(sha256.New, []byte("{{API_KEY_SECRET}}")) + h.Write([]byte(dataToSign)) + signature := base64.RawURLEncoding.EncodeToString(h.Sum(nil)) + + // Combine the parts to form the final JWT + ablyJwt := base64Header + "." + base64Claims + "." + signature + log.Println("Ably JWT:", ablyJwt) +``` + +```flutter +final header = { + "typ": "JWT", + "alg": "HS256", + "kid": "{{API_KEY_NAME}}" +}; + +final currentTime = (DateTime.now().millisecondsSinceEpoch / 1000).round(); +final claims = { + "iat": currentTime, /* current time in seconds */ + "exp": currentTime + 3600, /* time of expiration in seconds */ + "x-ably-capability": "{\"*\":[\"*\"]}" +}; + +final base64Header = base64UrlEncode(utf8.encode(json.encode(header))); +final base64Claims = base64UrlEncode(utf8.encode(json.encode(claims))); +final hmacSha256 = Hmac(sha256, utf8.encode("$base64Header.$base64Claims")); +final digest = hmacSha256.convert(utf8.encode("{{API_KEY_SECRET}}")); +final signature = base64UrlEncode(digest.bytes); +final ablyJwt = "$base64Header.$base64Claims.$signature"; +``` + + +At present Ably does not support asymmetric signatures based on a key pair belonging to a third party. + +### Embed an Ably Token in a JWT + +If a system has an existing [JWT](https://jwt.io/) scheme, it's possible to embed an Ably Token as a claim within it. + +The JWT and embedded token need to meet the following requirements: + +* The embedded token is an [Ably Token](#tokens). +* The embedded token is included under the `x-ably-token` key in the [JOSE Header](https://tools.ietf.org/html/rfc7519), or if using JWS, the embedded token is included using the `x-ably-token` claim in the payload. +* The expiry time of the embedded token must not be earlier than the outer JWT's expiry time (`exp` claim). Ably will reject any JWT if it is unencrypted and its `exp` claim is later than the expiry of the enclosed token. This helps to ensure that tokens are renewed prior to expiry. + +The process used by Ably SDKs to authenticate with Ably using an Ably Token embedded in a JWT is illustrated in the following diagram: + +![Token embedded in a JWT auth method](../../../images/content/diagrams/Ably-Auth-Overview3.png) + +The following is an example of issuing an Ably Token inside the of header of a JWT. Note that the authenticity of the JWT will not be checked, due to Ably not having access to your `SECRET` key. + + +```javascript +const ably = new Ably.Rest({ key: '{{API_KEY}}' }); +const tokenDetails = await ably.auth.requestToken({ clientId: 'client@example.com' }); +const header = { + "typ":"JWT", + "alg":"HS256", + "x-ably-token": tokenDetails.token +} +const claims = { + "exp": currentTime + 3600 +} +const base64Header = btoa(header); +const base64Claims = btoa(claims); +/* Apply the hash specified in the header */ +const signature = hash((base64Header + "." + base64Claims), SECRET); +const jwt = base64Header + "." + base64Claims + "." + signature; +/* Send jwt to client */ +``` + +```python + rest = AblyRest(key='{{API_KEY}}') + token_request_data = { + 'clientId': 'client@example.com', + } + + token_details = await rest.auth.request_token(token_params=token_request_data) + + header = { + "typ": "JWT", + "alg": "HS256", + "x-ably-token": token_details.token + } + claims = { + "exp": int(time.time()) + 3600 + } + + base64_header = base64.urlsafe_b64encode(bytes(json.dumps(header), 'utf-8')).decode('utf-8') + base64_claims = base64.urlsafe_b64encode(bytes(json.dumps(claims), 'utf-8')).decode('utf-8') + + signature = hashlib.sha256((base64_header + "." + base64_claims + "{{API_KEY_SECRET}}").encode('utf-8')).digest() + signature_base64 = base64.urlsafe_b64encode(signature).decode('utf-8') + + jwt_token = base64_header + "." + base64_claims + "." + signature_base64 +``` + +```java +ClientOptions options = new ClientOptions("{{API_KEY}}"); +AblyRest rest = new AblyRest(options); + +Auth.TokenParams tokenParams = new Auth.TokenParams(); +tokenParams.clientId = "client@example.com"; + +Auth.TokenDetails tokenDetails = rest.auth.requestToken(tokenParams, null); + +Map headerClaims = new HashMap<>(); +headerClaims.put("typ", "JWT"); +headerClaims.put("alg", "HS256"); +headerClaims.put("x-ably-token", tokenDetails.token); + +// Time of expiration in seconds (an hour) +long currentTimeInSeconds = System.currentTimeMillis() / 1000; + +// Define the claims +Map claims = new HashMap<>(); +claims.put("exp", currentTimeInSeconds + 3600); + +// Create the JWT +Algorithm algorithm = Algorithm.HMAC256("{{API_KEY_SECRET}}"); +String token = JWT.create() + .withHeader(headerClaims) + .withPayload(claims) + .sign(algorithm); +``` + +```php +$rest = new Ably\AblyRest( + ['key' => '{{API_KEY}}'] +); +$tokenDetails = $rest->auth->requestToken( + ['clientId' => 'client@example.com'] +); +$header = [ + 'typ' => 'JWT', + 'alg' => 'HS256', + 'x-ably-token' => $tokenDetails->token +]; +$currentTime = time(); +$claims = [ + 'exp' => $currentTime + 3600 /* time of expiration in seconds (an hour) */ +]; +$base64Header = base64_encode(json_encode($header)); +$base64Claims = base64_encode(json_encode($claims)); +$secret = 'YOUR_SECRET'; +$signature = hash_hmac('sha256', $base64Header . '.' . $base64Claims, $secret, true); +$base64Signature = base64_encode($signature); +$jwt = $base64Header . '.' . $base64Claims . '.' . $base64Signature; +``` + +```go +rest, err := ably.NewREST(ably.WithKey("{{API_KEY}}")) +if err != nil { + log.Fatalf("Failed to create Ably REST client: %v", err) +} + +// Request a token +tokenParams := &ably.TokenParams{ + ClientID: "client@example.com", +} +tokenDetails, err := rest.Auth.RequestToken(context.Background(), tokenParams) +if err != nil { + log.Fatalf("Failed to request token: %v", err) +} + +// Get the current time in seconds +currentTime := time.Now().Unix() + +// Create JWT header +header := map[string]interface{}{ + "typ": "JWT", + "alg": "HS256", + "x-ably-token": tokenDetails.Token, +} + +// Create JWT claims +claims := map[string]interface{}{ + "exp": currentTime + 3600, // time of expiration in seconds +} + +// Encode header to base64 +headerJSON, err := json.Marshal(header) +if err != nil { + log.Fatalf("Failed to marshal header: %v", err) +} +base64Header := base64.RawURLEncoding.EncodeToString(headerJSON) + +// Encode claims to base64 +claimsJSON, err := json.Marshal(claims) +if err != nil { + log.Fatalf("Failed to marshal claims: %v", err) +} +base64Claims := base64.RawURLEncoding.EncodeToString(claimsJSON) + +// Create the signature +dataToSign := base64Header + "." + base64Claims +h := hmac.New(sha256.New, []byte("SECRET")) +h.Write([]byte(dataToSign)) +signature := base64.RawURLEncoding.EncodeToString(h.Sum(nil)) + +// Combine the parts to form the final JWT +jwt := base64Header + "." + base64Claims + "." + signature +log.Println("JWT:", jwt) + +// Send JWT to client (for demonstration, print it here) +``` + +```flutter +final clientOptions = ably.ClientOptions( + key: '{{API_KEY}}', +); +final rest = ably.Rest(options: clientOptions); +const tokenParams = ably.TokenParams( + clientId: 'client@example.com', +); +final tokenDetails = await rest.auth.requestToken( + tokenParams: tokenParams +); + +final header = { + "typ": "JWT", + "alg": "HS256", + "x-ably-token": tokenDetails.token +}; + +final currentTime = (DateTime.now().millisecondsSinceEpoch / 1000).round(); +final claims = { + "iat": currentTime, /* current time in seconds */ + "exp": currentTime + 3600, /* time of expiration in seconds */ + "x-ably-capability": "{\"*\":[\"*\"]}" +}; + +final base64Header = base64UrlEncode(utf8.encode(json.encode(header))); +final base64Claims = base64UrlEncode(utf8.encode(json.encode(claims))); +final hmacSha256 = Hmac(sha256, utf8.encode("$base64Header.$base64Claims")); +final digest = hmacSha256.convert(utf8.encode("{{API_KEY_SECRET}}")); +final signature = base64UrlEncode(digest.bytes); +final ablyJwt = "$base64Header.$base64Claims.$signature"; +``` + + +## Dynamic channel access control + +Token authentication allows you to dynamically change a client's channel access permissions without disconnecting. Use the [`authorize()`](/docs/api/realtime-sdk/authentication#authorize) method to re-authenticate with updated [capabilities](/docs/auth/capabilities). + +When you call `client.auth.authorize()`: + +1. The client obtains a new token with different capabilities from your authentication server. +2. The new token is sent to Ably using the existing realtime connection. +3. The updated permissions are automatically applied without disconnecting. + +### Use cases + +You can trigger re-authentication in response to: +- Detect error code [40160](/docs/platform/errors/codes#40160) when a client attempts to attach to a channel. +- Instruct clients to re-authenticate via Ably channels or other communication methods. + + +The following example shows how to re-authenticate with updated capabilities: + + +```javascript +// Re-authenticate to get new capabilities +try { + const newTokenDetails = await client.auth.authorize({ + clientId: 'user123', + // Your auth server will return a token with updated capabilities + }); + console.log('Successfully updated permissions'); +} catch (error) { + console.error('Failed to re-authenticate:', error); +} +``` + + + +For security purposes, handle non-compliant clients by: +- Set shorter token TTL expiry times to force frequent re-authentication (minimum 10 minutes recommended). +- Use the [token revocation API](/docs/auth/revocation) to immediately invalidate tokens. + + + +## When to use token auth + +Ably recommends that token authentication is used client-side for the following reasons: + +* Tokens ensure that an Ably API key isn't exposed in client applications. +* Tokens are short-lived so there is only a short period of time during which a compromised token can be used. +* Tokens provide more fine-grained access control, which also limits the area of exposure a compromised token can access. + + diff --git a/src/pages/docs/channels/options/encryption.mdx b/src/pages/docs/channels/options/encryption.mdx index 645114aeb5..1325cdf4e7 100644 --- a/src/pages/docs/channels/options/encryption.mdx +++ b/src/pages/docs/channels/options/encryption.mdx @@ -32,7 +32,7 @@ Unencrypted communication with Ably is **disallowed** if any of the following co * You attempt to use [Basic Authentication](/docs/auth/basic) and thus transmit a private API key over an unencrypted connection. You are only permitted to use unencrypted connections with [Token Authentication](/docs/auth/token) as tokens expire, limiting the impact of token interception. -* You have specified that TLS is required in your [app settings](/docs/platform/account/app/settings). +* You have specified that TLS is required in your [app settings](/docs/platform/account/app/configuration/settings). * A client using an unencrypted connection attempts to attach to a channel that is configured to be used with [TLS only](/docs/channels#rules). diff --git a/src/pages/docs/metadata-stats/metadata/subscribe.mdx b/src/pages/docs/metadata-stats/metadata/subscribe.mdx index dfddb17ba8..f645267625 100644 --- a/src/pages/docs/metadata-stats/metadata/subscribe.mdx +++ b/src/pages/docs/metadata-stats/metadata/subscribe.mdx @@ -58,7 +58,7 @@ The `data` property of all events is a [`ChannelDetails`](/docs/api/realtime-sdk ### Regional channel activity -Seeing `channel.region.inactive` events in your [Dev Console](/docs/platform/account/app/console) logs is normal behavior. Channels become active in different regions globally according to where clients are located and Ably's internal placement rules. +Seeing `channel.region.inactive` events in your [Web Client](/docs/platform/account/app/client) logs is normal behavior. Channels become active in different regions globally according to where clients are located and Ably's internal placement rules. A `channel.region.inactive` event indicates that a channel no longer has any clients in that specific region, or that the channel is shutting down altogether. This is part of Ably's normal operation to efficiently manage resources across its global infrastructure. diff --git a/src/pages/docs/platform/account/2fa.mdx b/src/pages/docs/platform/account/2fa.mdx index 57ee9560f6..5781da35e7 100644 --- a/src/pages/docs/platform/account/2fa.mdx +++ b/src/pages/docs/platform/account/2fa.mdx @@ -8,28 +8,28 @@ redirect_from: Two-factor authentication (2FA) is an authentication process requiring users to utilize two different forms of verification. 2FA for your Ably account requires your password and a security token sent to your mobile phone. +Access your [account settings](https://ably.com/accounts/any/user/edit) to configure two-factor authentication for your Ably account. + ## Enable 2FA To enable 2FA for your own user login: -1. Log in to your [account](https://ably.com/accounts/any). -2. Select **My Settings** from the account navigation dropdown. -3. Toggle **Enable Two-Factor Authentication** under the **Two-factor authentication** section. +1. Log in to your account and select [Profile Settings](https://ably.com/users/edit) in your account. +2. Toggle **Enable Two-Factor Authentication** under the **Two-factor authentication** section. * Re-enter your password as prompted. -4. Select your **Country**. -5. Enter your **Phone number** -6. Click **Next** to receive an SMS with a security token. -7. Enter the security token and click **Verify security code**. -8. Scan the QR code into an authenticator app such as Authy, or Google Authenticator. -9. Store your recovery codes in a safe location. +3. Select your **Country**. +4. Enter your **Phone number** +5. Click **Next** to receive an SMS with a security token. +6. Enter the security token and click **Verify security code**. +7. Scan the QR code into an authenticator app such as Authy, or Google Authenticator. +8. Store your recovery codes in a safe location. ### Disable 2FA To disable 2FA for your own user login: -1. Log in to your [account](https://ably.com/accounts/any). -2. Select **My Settings** from the account navigation dropdown. -3. Click the **Disable Two-Factor Authentication** button. +1. Log in to your account and select [Profile Settings](https://ably.com/users/edit) in your account. +2. Click the **Disable Two-Factor Authentication** button. * Re-enter your password as prompted. ### Change phone number @@ -50,16 +50,14 @@ The account owner must already have 2FA enabled for their own login before they To enforce 2FA for all users: -1. Log in to your [account](https://ably.com/accounts/any). -2. Select **Settings** from the account navigation dropdown. -3. Toggle **Require Two-Factor Authentication for all account users** under the **Authentication Settings** section. -4. **Save** the authentication settings. +1. Log in to your account and select [Profile Settings](https://ably.com/users/edit) in your account. +2. Toggle **Require Two-Factor Authentication for all account users** under the **Authentication Settings** section. +3. **Save** the authentication settings. ### Remove 2FA requirement of all users To remove the requirement for all users to authenticate with 2FA: -1. Log in to your [account](https://ably.com/accounts/any). -2. Select **Settings** from the account navigation dropdown. -3. Toggle **Require Two-Factor Authentication for all account users** under the **Authentication Settings** section. -4. **Save** the authentication settings. +1. Log in to your account and select [Profile Settings](https://ably.com/users/edit) in your account. +2. Toggle **Require Two-Factor Authentication for all account users** under the **Authentication Settings** section. +3. **Save** the authentication settings. diff --git a/src/pages/docs/platform/account/app/api.mdx b/src/pages/docs/platform/account/app/api.mdx deleted file mode 100644 index 611776924c..0000000000 --- a/src/pages/docs/platform/account/app/api.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: API keys -meta_description: “Manage Ably API keys by creating, updating, setting restrictions, and exploring integration options.” -meta_keywords: "API keys, Ably, create key, update key, key restrictions, integration, webhooks, authentication" -redirect_from: - - /docs/account/app/api ---- - -The API keys tab lists all API keys associated with your account and provides information on each key's capabilities and restrictions. You can [create a new API key](#create) and manage an existing one. - - - -## Create a new API key - -The following steps create a new API Key: - -* Click **Create a new API key**. - * Assign a friendly name. - * Give the new API key a descriptive name (e.g. chat app key) so it is easy to identify later. - -To manage an API key: set [capabilities](/docs/auth/capabilities), define resource restrictions, use revocable tokens for security, and adjust key settings as needed. - -### Capabilities - -[Capabilities](/docs/auth/capabilities) provide permissions required for managing message flow, user presence, notifications, channel information, and access controls, these depend on what you require the API key to have access to: - -| Capability | Description | -| ---------- | ----------- | -| **Publish** | Allow clients to publish messages to channels. | -| **Subscribe** | Allow clients to receive messages and presence state changes. | -| **History** | Allow clients to retrieve message and presence history. | -| **Presence** | Allow clients to register presence on a channel. | -| **Channel metadata** | Allow clients to query channel metadata. | -| **Push admin and push-subscribe** | Allow clients to manage and subscribe to push notifications. | -| **Statistics** | Allow clients to query usage statistics. | -| **Privileged headers** | Allow clients to set privileged headers, such as to skip rules. | - -### Set resource restrictions - -Set resource restrictions to control access to channels and queues, ranging from unrestricted access to specific, rule-based permissions: - -| Restriction | Description | -| ----------- | ----------- | -| None | No restrictions; access any channel or queue. | -| Only channels | Access any channel but not queues. | -| Only queues | Access any queue but not channels. | -| Selected channels and queues | Specify explicit rules for access. | - -When specifying selected channels and queues, you can provide a comma-separated list of resources. Each resource can match a single channel (e.g., `channel-name`) or multiple channels using wildcards (e.g., `namespace:*`). Queues use the prefix `[queue]` and meta channels use `[meta]`. See [capabilities documentation](/docs/auth/capabilities#wildcards) for detailed wildcard syntax. - - - -### Revocable tokens - -[Revocable tokens](/docs/auth/revocation#revocable-tokens) enhance security by allowing shorter token lifetimes and the ability to revoke tokens issued via the API key. - -| Option | Description | -| ------ | ----------- | -| Revocable tokens | Implement security measures by setting shorter token lifetimes and enabling the ability to revoke tokens issued by the API key. | - -### Change your API key settings - -Click **Settings** on the required API key to change its settings. The same settings apply as when creating a new API key. diff --git a/src/pages/docs/platform/account/app/client.mdx b/src/pages/docs/platform/account/app/client.mdx new file mode 100644 index 0000000000..f7ae76410f --- /dev/null +++ b/src/pages/docs/platform/account/app/client.mdx @@ -0,0 +1,80 @@ +--- +title: Web client +meta_description: "Test and debug your application using the browser-based web client for realtime messaging, channel monitoring, and event tracking." +meta_keywords: "Ably web client, browser testing, realtime monitoring, connection status changes, channel activity, event logs, dev console, console" +redirect_from: + - /docs/account/app/console + - /docs/platform/account/app/console +--- + +The web client provides a browser-based interface for testing and debugging your realtime application. Access the web client through your [app dashboard](https://ably.com/accounts/any/apps/any/console) under the Console section. It offers realtime insights into application-wide events, such as connection status changes and channel activity. + +![Web client interface](../../../../../images/content/screenshots/dash/web-client.png) + +These features enable you to: + +* Observe changes in connection status across the application. +* View activity on specific channels, including message traffic and channel events. +* Examine event logs to troubleshoot your application. + + + +## Application-wide events interface + +The application-wide events interface allows you to monitor your application's health and activity in realtime. + +The following explains the realtime monitoring tools in the application-wide events interface: + +| Field | Description | +| ----- | ----------- | +| API key | The API key to access and view events within the app. | +| Average application-wide events per second (p/s) | This metric shows the average number of events occurring per second across your application. For example, if the current rate is 0, no active events are being processed. | +| Event log table | The event log table displays a record of events related to the current client's connection status. This table can be used to debug potential issues in your application. | + +## Message auditing and logging + +The web client displays messages in realtime for debugging and testing purposes, but does not provide persistent message auditing or logging capabilities. Ably does not currently offer native functionality to view historical messages filtered by specific channels or client IDs for auditing purposes. + +If you need to audit or log messages by channel or client ID, implement this functionality on the application side. Consider using: + +- [Webhooks](/docs/platform/integrations/webhooks) to send message events to your logging system +- [Message queues](/docs/platform/integrations/queues) to process and store message data +- Client-side logging in your application code + +For native message auditing features, [contact support](mailto:support@ably.com) to discuss requirements. + +## Channels + +The following is a step-by-step instructions for connecting to a channel, publishing messages. + +### Connect to a channel + +Connect to a channel: + +1. In the channel name field, choose a name (for example, get-started). +2. Click the **attach to channel** button. This connects you to the **get-started** channel, enabling you to start publishing or subscribing to messages. +3. The interface will display the channel status as **pending** and then **attached** once connected, confirming that the channel is ready for interaction. + +### Publish a message + +Publish a message: + +1. In the **message data** field, type a message (for example, "example"). +2. Click the **publish message** button to send the message to the **get-started** channel. +3. If you have a subscriber, it will receive and display the message in the console. + +Interact with presence: + +1. Enter a unique client ID to simulate joining the presence of the channel. +2. Click **enter presence** to indicate that this client is now in the channel. +3. The interface will list all clients in the channel under **presence members**. + +### Control the channel + +Control the channel in the web client: + +* Click **detach** to disconnect from the channel. +* Use **pause** to temporarily stop receiving messages. +* Click **clear** to clear the channel data or logs from the interface. diff --git a/src/pages/docs/platform/account/app/configuration/api-keys.mdx b/src/pages/docs/platform/account/app/configuration/api-keys.mdx new file mode 100644 index 0000000000..73e7d6d7df --- /dev/null +++ b/src/pages/docs/platform/account/app/configuration/api-keys.mdx @@ -0,0 +1,48 @@ +--- +title: API keys +meta_description: “Manage Ably API keys by creating, updating, setting restrictions, and exploring integration options.” +meta_keywords: "API keys, Ably, create key, update key, key restrictions, integration, webhooks, authentication" +redirect_from: + - /docs/account/app/api + - /docs/platform/account/app/api +--- + +The API keys tab lists all API keys associated with your account and provides information on each key's capabilities and restrictions. Manage your API keys in the [app dashboard](https://ably.com/accounts/any/apps/any/app_keys) under the API Keys section. You can [create a new API key](#create) and manage an existing one. + +![API keys management interface](../../../../../../images/content/screenshots/dash/keys.png) + + + +## Create a new API key + +Create a new API key: + +1. Click "Create a new API key". +2. Assign a friendly name. +3. Give the new API key a descriptive name (for example, chat app key) so it is easy to identify later. + +To manage an API key: set [capabilities](/docs/auth/capabilities), define resource restrictions, use revocable tokens for security, and adjust key settings as needed. + +### Capabilities + +[Capabilities](/docs/auth/capabilities) define which permissions your API key has. You can select from core messaging capabilities (subscribe, publish, presence), content management (message updates/deletes, annotations), data access (history, stats), push notifications, and administrative features. + +### Set resource restrictions + +Control which channels and queues the API key can access. You can choose from "None" (unrestricted access), "Only channels" (no queue access), "Only queues" (no channel access), or "Selected channels and queues" for specific access rules. + +When selecting specific resources, provide a comma-separated list. Use exact names (`channel-name`) or wildcards (`namespace:*`). Queues need the `[queue]` prefix and meta channels use `[meta]`. See [capabilities documentation](/docs/auth/capabilities#wildcards) for wildcard syntax. + + + +### Revocable tokens + +Enable [revocable tokens](/docs/auth/revocation#revocable-tokens) to enhance security by allowing shorter token lifetimes and the ability to revoke tokens issued by this API key. + +### Change your API key settings + +Click "Settings" on the required API key to change its settings. The same settings apply as when creating a new API key. diff --git a/src/pages/docs/platform/account/app/configuration/integrations.mdx b/src/pages/docs/platform/account/app/configuration/integrations.mdx new file mode 100644 index 0000000000..5ae2fa13d0 --- /dev/null +++ b/src/pages/docs/platform/account/app/configuration/integrations.mdx @@ -0,0 +1,23 @@ +--- +title: Integrations +meta_description: "Configure and manage integrations within the Ably dashboard." +meta_keywords: "Integrations, configuration, webhooks, dashboard, Ably" +--- + +The Integrations section allows you to connect your Ably application with external services and systems. Configure and manage your integrations in the [app dashboard](https://ably.com/accounts/any/apps/any/integrations). + +![Integration management interface](../../../../../../images/content/screenshots/dash/integration.png) + +## Available integration types + +You can configure the following types of integrations: + +- [Inbound webhooks](/docs/platform/integrations/webhooks#inbound) - Receive events from external services into Ably +- [Outbound webhooks](/docs/platform/integrations/webhooks) - Trigger serverless functions or custom servers on Ably events +- [Outbound streaming](/docs/platform/integrations/streaming) - Stream data to external systems like Kinesis or Kafka +- [Third-party integrations](/docs/platform/integrations) - Connect with external services like Datadog + + + diff --git a/src/pages/docs/platform/account/app/configuration/rules.mdx b/src/pages/docs/platform/account/app/configuration/rules.mdx new file mode 100644 index 0000000000..cd6a479dbd --- /dev/null +++ b/src/pages/docs/platform/account/app/configuration/rules.mdx @@ -0,0 +1,63 @@ +--- +title: Rules +meta_description: "Configure and manage rules within the Ably dashboard." +meta_keywords: "Rules, configuration, settings, dashboard, Ably" +--- + +Rules allow you to configure features for channels, rooms, or spaces within specified namespaces. Configure and manage your rules in the [app dashboard](https://ably.com/accounts/any/apps/any/rules). Rules control message persistence, authentication requirements, security settings, and other functionality. + +![Rules dashboard screenshot](../../../../../../images/content/screenshots/dash/rules.png) + +## Your rules + +The rules interface displays your configured namespace rules and their applied settings: + +### Channel namespace configuration + +Each rule is defined by a channel namespace pattern that determines which channels the rule applies to: + +| Configuration element | Description | +|---|---| +| Channel namespace | The namespace pattern that determines which channels the rule applies to | + +For example, a namespace `coco` would apply to channels matching the pattern, with example matches like `coco:data` or `coco`. + +## Available features + +The Rules system provides access to multiple feature categories that can be enabled for your namespaces: + +### Message persistence features + +Control how messages are stored for channels in this namespace: + +| Feature | Description | +|---|---| +| Persist last message | Store the most recent message published to channels. | +| Persist all messages | Store all messages published to channels. | + +### Security and access features + +Enforce security requirements for channels in this namespace: + +| Feature | Description | +|---|---| +| Identified | Require client identification for channel access. | +| TLS only | Enforce encrypted connections for channel access. | + +### Push notification features + +Configure push notification delivery for channels in this namespace: + +| Feature | Description | +|---|---| +| Push notifications | Enable push notification delivery. | + +### Message processing features + +Configure message processing behavior for channels in this namespace: + +| Feature | Description | +|---|---| +| Message interactions | Enable message references and threading. | +| Server-side batching | Enable message batching optimization. | +| Message conflation | Enable message optimization. | diff --git a/src/pages/docs/platform/account/app/configuration/settings.mdx b/src/pages/docs/platform/account/app/configuration/settings.mdx new file mode 100644 index 0000000000..7753f41d59 --- /dev/null +++ b/src/pages/docs/platform/account/app/configuration/settings.mdx @@ -0,0 +1,44 @@ +--- +title: Application settings +meta_description: "Configure and manage application settings within the Ably dashboard." +meta_keywords: "Settings, configuration, application, dashboard, Ably" +redirect_from: + - /docs/platform/account/app/settings + - /docs/account/app/settings +--- + +The Settings section allows you to configure your application's core settings, security requirements, and protocol support. Configure your application settings in the [app dashboard](https://ably.com/accounts/any/apps/any/settings). + +## Application settings + +The following settings define your application's identity: + +| Setting | Description | +|---|---| +| App ID | Unique identifier for your application. | +| Name | Friendly name for your application. | + +Configure security requirements that apply across your entire application: + +| Security setting | Description | +|---|---| +| TLS required | Enforce encrypted connections for all clients. | + + + +Control whether your application accepts connections and processes requests: + +| Status setting | Description | +|---|---| +| Active | Application operational status. | +| Enabled | Service availability status. | + +Protocol adapters allow clients using standard messaging protocols to connect to your Ably application without requiring Ably-specific client libraries: + +| Protocol | Description | +|---|---| +| [Pusher protocol support](/docs/protocols/pusher) | Compatibility with Pusher client libraries (optional). | +| [PubNub protocol support](/docs/protocols/pubnub) | Compatibility with PubNub client libraries (always-on). | +| [MQTT protocol support](/docs/protocols/mqtt) | Standard MQTT messaging protocol support (always-on). | diff --git a/src/pages/docs/platform/account/app/connections.mdx b/src/pages/docs/platform/account/app/connections.mdx new file mode 100644 index 0000000000..71c9233291 --- /dev/null +++ b/src/pages/docs/platform/account/app/connections.mdx @@ -0,0 +1,29 @@ +--- +title: Connections +meta_description: "Monitor and manage connections within the Ably dashboard." +meta_keywords: "Connections, monitoring, clients, dashboard, Ably" +--- + +The Connections section shows active client connections and their channel subscriptions. Monitor your connections through the [app dashboard](https://ably.com/accounts/any/apps/any/connections). + +## Connection browser + +The connections interface lists currently connected clients. You can filter by connection ID, client ID, country, and SDK version. + +![Connections interface](../../../../../images/content/screenshots/dash/connections.png) + +Each connection entry displays the connection ID, client ID (if set), geographic location, and SDK version. Click the inspect button (eye icon) to view detailed connection information. + +## Connection inspection + +The connection inspection page shows detailed information for a specific connection: + +- Connection details (client ID, transport type, creation timestamp, status, IP address, SDK version, platform) +- Authentication configuration (auth type, security protocol, API key identifier) +- Capabilities (which Ably features the client can use) +- Activity metrics (inbound and outbound message rates over time) +- Live logs (realtime events specific to this connection) + +## Attached channels + +The attached channels tab lists channels that the connection is subscribed to, including connection modes (presence, publish, subscribe) and activity metrics. Click inspect on any channel to navigate to the [channel inspection](/docs/platform/account/app/products/pubsub#inspection) interface. diff --git a/src/pages/docs/platform/account/app/console.mdx b/src/pages/docs/platform/account/app/console.mdx deleted file mode 100644 index aec15bb350..0000000000 --- a/src/pages/docs/platform/account/app/console.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Dev console -meta_description: "Gain realtime insights into application-wide events, such as connection status changes, channel activity, and event logs.” -meta_keywords: “Ably dev console, realtime monitoring, connection status changes, channel activity, event logs" -redirect_from: - - /docs/account/app/console ---- - -The dev console tab provides realtime insights into application-wide events, such as connection status changes and channel activity. These features enable you to: - -* Observe changes in connection status across the application. -* View activity on specific channels, including message traffic and channel events. -* Examine event logs to troubleshoot your application. - -## Application-wide events interface - -The application-wide events interface allows you to monitor your application's health and activity in realtime. - -The following explains the realtime monitoring tools in the application-wide events interface: - -| Field | Description | -| ----- | ----------- | -| **API key** | The API key to access and view events within the app. | -| **Average application-wide events per second (p/s)** | This metric shows the average number of events occurring per second across your application. For example, if the current rate is 0, no active events are being processed. | -| **Event log table** | The event log table displays a record of events related to the current client's connection status. This table can be used to debug potential issues in your application. | - -## Message auditing and logging - -The dev console displays messages in realtime for debugging and testing purposes, but does not provide persistent message auditing or logging capabilities. Ably does not currently offer native functionality to view historical messages filtered by specific channels or client IDs for auditing purposes. - -If you need to audit or log messages by channel or client ID, implement this functionality on the application side. Consider using: - -- [Webhooks](/docs/platform/integrations/webhooks) to send message events to your logging system -- [Message queues](/docs/platform/integrations/queues) to process and store message data -- Client-side logging in your application code - -For native message auditing features, [contact support](mailto:support@ably.com) to discuss requirements. - -## Channels - -The following is a step-by-step instructions for connecting to a channel, publishing messages. - -### Connect to a channel - -The following explains how to connect to a channel: - -| Step | Action | -| ---- | ------ | -| **Enter a channel name** | In the channel name field, choose a name (e.g get-started). | -| **Attach to channel** | Click the **attach to channel** button. This connects you to the **get-started** channel, enabling you to start publishing or subscribing to messages. | -| **Monitor channel status** | The interface will display the channel status as **pending** and then **attached** once connected, confirming that the channel is ready for interaction.| - -### Publish a message - -The following explains how to publish a message: - -| Step | Action | -| ---- | ------ | -| **Message data** | In the **message data** field, type a message (e.g. example). | -| **Publish message** | Click the **publish message** button to send the message to the **get-started** channel. | -| **View the message** | If you have a subscriber , it will receive and display the message in the console. | - -The following explains how to interact with presence: - -| Step | Action | -| ---- | ------ | -| **Client ID** | Enter a unique client ID to simulate joining the presence of the channel. | -| **Enter presence** | Click **enter presence** to indicate that this client is now in the channel. | -| **Monitor presence** | The interface will list all clients in the channel under **presence members**. | - -### Control the channel - -The following explains how to control the channel in the dev console: - -| Step | Action | -| ---- | ------ | -| **Detach** | Click **detach** to disconnect from the channel. | -| **Pause** | Use **pause** to temporarily stop receiving messages. | -| **Clear** | Click **clear** to clear the channel data or logs from the interface. | diff --git a/src/pages/docs/platform/account/app/index.mdx b/src/pages/docs/platform/account/app/index.mdx index 28d96d01f6..78611c2075 100644 --- a/src/pages/docs/platform/account/app/index.mdx +++ b/src/pages/docs/platform/account/app/index.mdx @@ -8,100 +8,118 @@ redirect_from: Manage and monitor your applications on the Ably platform using the Ably dashboard. Create new apps, view existing ones, and configure settings from your browser. -Begin by [logging](https://ably.com/login) in to Ably through your browser. Once you're logged in, you have access to the Ably [dashboard](https://ably.com/accounts), where you can [create a new app](#create) or [view your existing apps.](#view) +![Dashboard overview interface](../../../../../images/content/screenshots/dash/overview.png) -## Create a new app +### Navigation structure -The following image displays the Ably dashboard when no apps have been created yet. To get started, you can easily **Create new app**: +The dashboard is organized into several main sections: -![Create apps in the Ably dashboard](../../../../../images/content/screenshots/dash/create-app.png) +- [Products](#products): Core Ably services including Pub/Sub, Chat, Spaces, LiveObjects, LiveSync, and Push Notifications +- [Platform](#platform): Infrastructure components like Connections and Queues +- [Monitoring](#monitoring): Logs and Reports for tracking performance and debugging +- [Configuration](#configuration): Rules, Integrations, API Keys, and Settings for customizing your application -## View your apps +### Live statistics -If you have created apps already, your dashboard will look similar to the one shown in the following image. Each app displayed is a link to its specific dashboard, where you can view and configure settings, as well as monitor usage and statistics: +Monitor your application's realtime performance with live statistics displayed prominently on the dashboard. View current activity like active connections and channels, message rates, and monthly totals including peak usage metrics. -![Your apps in the Ably dashboard](../../../../../images/content/screenshots/dash/your-apps.png) +## Products -### Environments +Your app dashboard provides access to Ably's core products for building realtime applications: -Each Ably app acts as a sandboxed environment, isolated from other apps in your account. This makes it straightforward to set up separate environments for development, staging, and production by creating dedicated apps for each. +### Pub/Sub -For example, if you're building a product called "chat-app", you could create: +Publish and subscribe to realtime messages across channels for instant communication between clients and servers. -- `chat-app-production` for your live production environment -- `chat-app-staging` for pre-production testing -- `chat-app-development` for ongoing development work +Access the [channel overview](https://ably.com/accounts/any/apps/any/channels) to monitor usage and manage individual channels, or use the [web client](https://ably.com/accounts/any/apps/any/console) for browser-based testing. -This approach provides complete isolation between environments, ensuring that development activities don't interfere with production traffic. An alternative approach for complete resource isolation, consider using separate Ably accounts for development and production environments. This ensures development activities cannot impact production resources under any circumstances. +### Chat - +Build chat applications with message history, user presence, and moderation capabilities for engaging conversational experiences. -## App overview +Access the [chat overview](https://ably.com/accounts/any/apps/any/chat) to monitor usage and [manage chat rooms](https://ably.com/accounts/any/apps/any/rooms). -Your app dashboard provides the following tabs for monitoring and configuring your app settings: +### Spaces -![Your app dashboard tabs](../../../../../images/content/screenshots/dash/dash-tabs.png) +Create collaborative spaces with member awareness and live cursors for realtime collaborative applications. -### Stats +Access the [spaces overview](https://ably.com/accounts/any/apps/any/spaces) to monitor usage and [manage individual spaces](https://ably.com/accounts/any/apps/any/spaces/spaces). -Monitor and analyze your app's performance through a [stats](/docs/platform/account/app/stats) table and chart: +### LiveObjects -* Track messages, presence events, and performance metrics to understand usage and capacity. -* Compare data over time to identify trends and optimize resources. -* Adjust chart views with zoom options and set specific time ranges for detailed insights. +Synchronize application state in realtime across connected clients for shared data experiences. -### Getting started +Access the [LiveObjects overview](https://ably.com/accounts/any/apps/any/liveobjects) to monitor usage and performance metrics. -Get started by connecting to Ably, and publishing your first message. +### LiveSync -### API keys +Stream database changes to frontend applications instantly for reactive user interfaces. -Create, manage, and configure [API keys](/docs/platform/account/app/api) by setting capabilities: +Access the [LiveSync overview](https://ably.com/accounts/any/apps/any/livesync) to monitor usage and performance metrics. -* Users can create a new API key, assigning a descriptive name for easy identification. -* Capabilities include permissions like publishing messages, subscribing to channels, retrieving message history, managing presence, and accessing statistics. -* Control access by defining whether the key has unrestricted access, channel-only, queue-only, or specific access to selected channels and queues. +### Push Notifications -### Integrations +Send notifications to mobile devices and web browsers to keep users engaged and informed. -[Integrate](/docs/platform/integrations) Ably with external services, enabling data to flow between Ably channels and third-party platforms: +Access the [push notifications overview](https://ably.com/accounts/any/apps/any/push) to configure services, inspect registrations, and manage device subscriptions. -* Ably events can trigger webhook requests to external services, or external services can send data to Ably using incoming webhooks. -* Ably enables continuous streaming of events to external services like Amazon Kinesis or Kafka, or can receive inbound streams from external services. -* Ably supports various integration methods, including HTTP callbacks, cloud functions, and streaming services. +## Platform -### Queues +Monitor and manage your application's infrastructure components: -View, monitor, and adjust Ably [queues:](/docs/platform/account/app/queues) +### Connections -* Queues provide access to manage existing queues, monitor data flow, and adjust settings such as TTL, max length, and region. -* Users can contact Ably support for assistance with increasing limits or customizing their queue settings. +Monitor active client connections and connection statistics to understand your application's usage patterns. -### Notifications +Access the [connections page](https://ably.com/accounts/any/apps/any/connections) to search for specific connections, filter by country or SDK version, and inspect connection details. -Manage [notifications](/docs/platform/account/app/notifications) using Ably. Create, test, and send notifications to specific devices or channels, and enure everything works correctly. +### Queues -* Configure push notifications for devices using FCM for Android or APNs for iOS. -* Use the push inspector tool to test and debug notifications by sending them manually and reviewing device, client, and channel registrations. -* Use the push inspector widget below to browse and inspect channel subscriptions, device and client registrations. +Manage message queues for reliable message delivery and processing in asynchronous workflows. -### Dev console +Access [queue overview](https://ably.com/accounts/any/apps/any/queues) to view and manage your queues, or [create new queues](https://ably.com/accounts/any/apps/any/queues/new) with customizable settings. -Monitor your application's health in realtime using Ably's [dev console](/docs/platform/account/app/console) by -- tracking events like connection status changes and channel activity. Connect to channels, publish messages, manage presence, and view event logs for troubleshooting: +## Monitoring -* The dev console provides realtime insights into application-wide events like connection status changes, channel activity, and event logs. -* You can connect to channels, publish messages, and manage presence, tracking interactions within the channel through the console. -* The event log table displays detailed records of connection events, which can be used for troubleshooting and diagnosing application issues. -* Interact with Ably channels using command-line tools like cURL. +Monitor your application's performance and troubleshoot issues: -### Settings +### Logs -Manage key aspects of your application [settings](/docs/platform/account/app/settings), including security, enabling or disabling the app, configuring rules for channels, and setting up protocol support for different SDKs: +Access detailed logging information to monitor and debug your application activity. -* Manage settings like App ID, name, security (TLS), and enable/disable the application, affecting its ability to accept connections and use Ably services. -* Create rules to enforce settings for specific channels, or channel namespaces, such as message persistence, TLS-only access, push notifications, and server-side batching. -* Enable compatibility with various protocols like Pusher, PubNub, and MQTT for communication between client libraries and Ably. -* Manage notifications for channel activity and occupancy to gain realtime insights into channel usage and performance. +Access the [logs page](https://ably.com/accounts/any/apps/any/logs) to view API requests, channel activity, connection events, integration errors, and push notification logs. + +### Reports + +Analyze your application's performance, usage patterns, and billable consumption metrics. + +Access the [reports page](https://ably.com/accounts/any/apps/any/reports) to view detailed analytics and usage statistics. + +## Configuration + +Configure and customize your application's behavior and integrations: + +### Rules + +Set up automated message routing and transformations to process messages as they flow through your application. + +Access the [rules page](https://ably.com/accounts/any/apps/any/rules) to configure authentication requirements, message persistence, and push notifications for channels within specified namespaces. + +### Integrations + +Connect external services like webhooks, Kafka, and cloud functions to extend your application's capabilities. + +Access the [integrations page](https://ably.com/accounts/any/apps/any/integrations) to configure webhooks, Ably Queues, and Firehose for streaming data to third-party systems. + +### API Keys + +Create and manage authentication keys with specific capabilities to control access to your application's resources. + +Access the [API keys page](https://ably.com/accounts/any/apps/any/app_keys) to manage secure app authentication, create new keys, and configure capabilities and resource restrictions. + +### Settings + +Configure app-level settings including security and protocol support to customize your application's behavior. + +Access the [settings page](https://ably.com/accounts/any/apps/any/edit?focus=settings) to manage application information, security settings, TLS enforcement, and protocol adapter settings. diff --git a/src/pages/docs/platform/account/app/monitoring.mdx b/src/pages/docs/platform/account/app/monitoring.mdx new file mode 100644 index 0000000000..cde1eebfe0 --- /dev/null +++ b/src/pages/docs/platform/account/app/monitoring.mdx @@ -0,0 +1,37 @@ +--- +title: Monitoring +meta_description: "Monitor logs and view reports within your Ably dashboard." +meta_keywords: "Logs, monitoring, debugging, reports, dashboard, Ably, usage, insights" +--- + +Use the monitoring section of the dashboard to view [logs](https://ably.com/accounts/any/apps/any/logs/api_requests_logs) and [reports](https://ably.com/accounts/any/apps/any/reports) for your applications. + +## Logs + +The [logs](https://ably.com/accounts/any/apps/any/logs/api_requests_logs) section provides historical event logging for monitoring and debugging your application. + +![API requests logs interface](../../../../../images/content/screenshots/dash/log1.png) + +Logs are organized by their specific resource: + +| Log section | Description | +|---|---| +| API requests | REST API calls and authentication attempts. | +| Channels | Channel lifecycle events. | +| Connections | Client connection lifecycle events. | +| Integration errors | Integration failures and webhook issues. | +| Push notifications | Push notification delivery errors. | + +Each section provides date range filtering and search capabilities for the specific type of events being monitored. + + + +## Reports + +The [reports](https://ably.com/accounts/any/apps/any/reports) section provides analytics and usage insights for your application. + + diff --git a/src/pages/docs/platform/account/app/notifications.mdx b/src/pages/docs/platform/account/app/notifications.mdx deleted file mode 100644 index 6e17b52961..0000000000 --- a/src/pages/docs/platform/account/app/notifications.mdx +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Notifications -meta_description: Configure credentials for integrating Ably's push notification services with third-party services, send push notifications from the Ably dashboard, and inspect push notifications .” -meta_keywords: “Ably push notifications, configure FCM, configure APNs, Web Push setup, push inspector" -redirect_from: - - /docs/account/app/notifications ---- - -Before you can start using Ably's [push notification](/docs/push) services, you must configure the credentials for the third-party services you wish to integrate, such as FCM for Android devices, APNs for iOS devices, or Web Push for web browsers. - -### Configure FCM for Android devices - -* Go to the [Firebase Console.](https://firebase.google.com/) -* Click **add project** and follow the steps to **create and manage service account keys**. -* Download your service account **JSON file**. -* In your Ably [dashboard](https://ably.com/accounts), navigate to the **notifications** tab under your app settings. -* Go to **push notifications setup**, click **configure push**. -* Add your service account **JSON file** to the **setting up Firebase cloud messaging** section. - -### Configure APNs for iOS devices - -* Go to the [Apple Developer Program.](https://developer.apple.com/programs/) -* Use the Apple developer portal to create a **push notification** service certificate for your app. -* Export the certificate as a **.p12 file**. -* Next, you can either import the **.p12 cert** or create a **PEM file** and copy it into your Ably dashboard: - -* Import the **.p12 file**: - * In your Ably [dashboard](https://ably.com/accounts), navigate to the **Notifications** tab under your app settings. - * Go to **push notifications setup**, click **configure push** and scroll to the **setting up Apple push notification service** section. - * Select the **.p12 file** you exported and enter the password you created during the export process. - * Click **save**. You should receive confirmation that the certificate has been successfully imported. - * To further confirm the import, refresh the page and check if the **PEM cert** and **private key** text boxes are now populated with the imported key details. -* Create a **PEM file** from the **.p12 file**: - * Using [OpenSSL](https://www.openssl.org/), convert the recently exported **.p12 file** (`io.ably.test.p12`) to a **PEM file** with the following command: `$ openssl pkcs12 -in ./io.ably.test.p12 -out ./io.ably.test.pem -nodes -clcerts`. - * Open the **PEM file** in your text editor. - * Copy everything between and including `-----BEGIN CERTIFICATE-----` and `-----END CERTIFICATE-----`, and paste it into the **PEM cert** text box of the Apple push notification service section of your Ably notifications app [dashboard](https://ably.com/accounts). - * Similarly, copy everything between and including `-----BEGIN PRIVATE KEY-----` and `-----END PRIVATE KEY-----`, and paste it into the **PEM private key** text box of the same section. Then, click **Save**. - -## Push inspector - -The Push inspector tool enables you to manually send push notifications by specifying the required data and notification fields. This tool helps test and debug your notification setup before going live. - -### API key - -The [API Key](/docs/platform/account/app/api) authenticates your requests when sending push notifications. Choose from the list of API keys associated with your Ably account. Each key has different permissions and scopes, so ensure you select the correct one for your notification tasks. - -### Push notification title and body - -Define the content of your push notification using the fields below: - -| Field | Purpose | How to Use | -| ----- | ------- | ---------- | -| Notification title | A title for the push notification, which will appear as the headline on the user's device. | Enter a short, clear title that captures the essence of the notification. | -| Notification body | The main content of the notification to be displayed below the title. | Write the key information or message that you want the user to read. | -| Notification data | Optional JSON data that the app can use for specific actions upon receiving the notification. | Include any extra data needed for app functionality, such as custom metadata or instructions. | - -### Push notification target - -Direct your push notifications to specific targets within the Ably platform. Select the appropriate target according to your notification strategy: - -| Target | Purpose | How to Use | -| ------ | ------- | ---------- | -| Channel name | Push notifications to all subscribers of a specific channel. | Enter the channel name and click push to channel to notify all devices subscribed to that channel. | -| Device ID | Send a notification directly to a specific device. | Enter the Device ID and click push to device to target a single device with the notification. | -| Client ID | Notify a specific client registered with Ably. | Enter the Client ID and click push to client to send the notification to the chosen client. | - -## Push inspector widget - -The Push Inspector widget allows you to monitor and manage your push notification infrastructure directly from the Ably dashboard. It provides insights into channel subscriptions, device registrations, and client registrations, making it easier to debug and optimize your notification setup. - -| Section | Purpose | How to Use | -| ------- | ------- | ---------- | -| Channel subscriptions | View and inspect all channels currently subscribed to push notifications. | Click inspect channel to see detailed information about a specific channel, including the number of subscribers and recent activity. | -| Device registrations | Access a list of all devices registered to receive push notifications. | Click inspect device to view detailed information about a specific device, such as its registration status, platform, and recent notifications. | -| Client registrations | Get an overview of all clients registered for push notifications within the Ably account. | Click inspect client ID to see detailed information about a specific client, including its subscriptions and recent activity. | diff --git a/src/pages/docs/platform/account/app/products/chat.mdx b/src/pages/docs/platform/account/app/products/chat.mdx new file mode 100644 index 0000000000..93cf9f82f1 --- /dev/null +++ b/src/pages/docs/platform/account/app/products/chat.mdx @@ -0,0 +1,32 @@ +--- +title: Chat +meta_description: "Manage and monitor your Chat functionality within the Ably dashboard." +meta_keywords: "Chat, rooms, messaging, users, dashboard, Ably" +--- + +The Chat section of the [app dashboard](https://ably.com/accounts/any/apps/any/rooms) provides tools for monitoring and managing realtime messaging across your application that is specific to [Ably Chat](/docs/chat). + +## Rooms + +The rooms section lists all active rooms with their connection counts. Use the search box to filter rooms by name. Click the inspect button on any room to view detailed information about that room, along with a live feed of events being published to it. + +### Room overview + +The room overview provides a realtime view of activity on the room, including: + +* Live analytics showing the current rate of messages on the room. +* Any configured [rules](/docs/channels#rules) that apply to the room. +* Any configured [integrations](/docs/integrations) that will run against the room. +* Live logs showing lifecycle events for that room, such as the regions it is active in. + +### Connections + +The connections tab lists all clients currently connected to the room. Click **Inspect** on any connection to view details of that [connection](/docs/platform/account/app/connections), including a list of rooms it is connected to. + +## Messages + +The messages tab displays a realtime view of messages and events being published to the room. + +## Presence + +The presence tab displays a realtime view of presence events occurring on the room, every time a client enters, leaves, or updates their presence state. diff --git a/src/pages/docs/platform/account/app/products/liveobjects.mdx b/src/pages/docs/platform/account/app/products/liveobjects.mdx new file mode 100644 index 0000000000..814271f263 --- /dev/null +++ b/src/pages/docs/platform/account/app/products/liveobjects.mdx @@ -0,0 +1,11 @@ +--- +title: LiveObjects +meta_description: "Manage and monitor your LiveObjects functionality within the Ably dashboard." +meta_keywords: "LiveObjects, synchronization, state management, realtime data, dashboard, Ably" +--- + +The LiveObjects section of the [app dashboard](https://ably.com/accounts/any/apps/any/liveobjects) provides tools for monitoring and managing synchronized state objects across your application. From this page, you can access getting started guides for different platforms and explore ready-to-use examples. + +## CLI + +The [Ably CLI](/docs/platform/tools/cli) provides command-line tools for managing LiveObjects operations, testing state synchronization, and automating workflows. \ No newline at end of file diff --git a/src/pages/docs/platform/account/app/products/livesync.mdx b/src/pages/docs/platform/account/app/products/livesync.mdx new file mode 100644 index 0000000000..6a4f29cd44 --- /dev/null +++ b/src/pages/docs/platform/account/app/products/livesync.mdx @@ -0,0 +1,14 @@ +--- +title: LiveSync +meta_description: "Manage and monitor your LiveSync functionality within the Ably dashboard." +meta_keywords: "LiveSync, database streaming, data synchronization, realtime updates, dashboard, Ably" +--- + +The LiveSync section in your Ably dashboard provides management tools for database streaming and data synchronization across your application. Access the [LiveSync dashboard](https://ably.com/accounts/any/apps/any/livesync) to monitor and manage your database streaming. From this overview page, you can quickly access getting started guides for different platforms, explore ready-to-use examples, and review recent product updates through the changelog. + +The dashboard makes it easy to monitor LiveSync implementation patterns and stay updated with the latest features and fixes. + +## CLI + +The [Ably CLI](/docs/platform/tools/cli) offers command-line tools for managing LiveSync operations, testing database streaming, and automating data synchronization workflows. Use it for scripting, CI/CD integration, and server-side debugging of your synchronized data streams. + diff --git a/src/pages/docs/platform/account/app/products/pubsub.mdx b/src/pages/docs/platform/account/app/products/pubsub.mdx new file mode 100644 index 0000000000..3e7b338acd --- /dev/null +++ b/src/pages/docs/platform/account/app/products/pubsub.mdx @@ -0,0 +1,36 @@ +--- +title: Pub/Sub +meta_description: "Manage and monitor your Pub/Sub functionality within the Ably dashboard." +meta_keywords: "Pub/Sub, channels, messaging, realtime, dashboard, Ably" +--- + +The Pub/Sub section of the [app dashboard](https://ably.com/accounts/any/apps/any/channels) provides tools for monitoring and managing realtime messaging across your application that is specific to [Ably Pub/Sub](/docs/basics). + +## Channels + +The channels section lists all active channels with their connection counts. Use the search box to filter channels by name. Click the inspect button on any channel to view detailed information about that channel, along with a live feed of events being published to it. + +### Channel overview + +The channel overview provides a realtime view of activity on the channel: + +![Channels inspector interface](../../../../../../images/content/screenshots/dash/channels1.png) + +This view also includes: + +* Live analytics showing the current rate of messages on the channel. +* Any configured [rules](/docs/channels#rules) that apply to the channel. +* Any configured [integrations](/docs/integrations) that will run against the channel. +* Live logs showing lifecycle events for that channel, such as the regions it is active in. + +### Connections + +The connections tab lists all clients currently connected to the channel. Click **Inspect** on any connection to view details of that [connection](/docs/platform/account/app/connections), including a list of channels it is connected to. + +## Messages + +The messages tab displays a realtime view of messages and events being published to the channel. + +## Presence + +The presence tab displays a realtime view of presence events occurring on the channel, every time a client enters, leaves, or updates their presence state. diff --git a/src/pages/docs/platform/account/app/products/push-notifications.mdx b/src/pages/docs/platform/account/app/products/push-notifications.mdx new file mode 100644 index 0000000000..d9b297fad5 --- /dev/null +++ b/src/pages/docs/platform/account/app/products/push-notifications.mdx @@ -0,0 +1,40 @@ +--- +title: Push notifications +meta_description: "Manage and monitor your Push Notifications functionality within the Ably dashboard." +meta_keywords: "Push notifications, FCM, APNS, notifications, mobile, dashboard, Ably" +redirect_from: + - /docs/account/app/notifications + - /docs/platform/account/app/notifications +--- + +Before you can start using Ably's push notification services, you must configure the credentials for the third-party services you wish to integrate: + +* [FCM](/docs/push/configure/device#fcm) for Android devices. +* [APNS](/docs/push/configure/device#apns) for iOS devices. +* [Web Push](/docs/push/configure/web) for web browsers. + +![Push notifications interface](../../../../../../images/content/screenshots/dash/push.png) + +## Push inspector + +The Push inspector enables you to manually send push notifications to test and debug your notification setup. + +Each push notification requires a title and body. You can also include extra data for app functionality: + +1. Write a short, clear title that captures the essence of the notification. +2. Include the key information or message that you want the user to read. +3. Optionally, add any extra data needed for app functionality, such as custom metadata or instructions. + +Push notifications can be sent to a channel, a specific device, or a specific client: + +* Channel: enter the channel name in the target field and click "push to channel". +* Device: enter the Device ID in the target field and click "push to device". +* Client: enter the Client ID in the target field and click "push to client". + +## Push inspector widget + +Use the Push inspector widget to monitor your push notification infrastructure. It provides inspection tools for channels, devices, and clients: + +* Channel subscriptions: view and inspect all channels currently subscribed to push notifications. +* Device registrations: access a list of all devices registered to receive push notifications. +* Client registrations: get an overview of all clients registered for push notifications within the Ably account. diff --git a/src/pages/docs/platform/account/app/products/spaces.mdx b/src/pages/docs/platform/account/app/products/spaces.mdx new file mode 100644 index 0000000000..541a20433c --- /dev/null +++ b/src/pages/docs/platform/account/app/products/spaces.mdx @@ -0,0 +1,36 @@ +--- +title: Spaces +meta_description: "Manage and monitor your Spaces functionality within the Ably dashboard." +meta_keywords: "Spaces, collaboration, presence, cursors, dashboard, Ably" +--- + +The Spaces section of the [app dashboard](https://ably.com/accounts/any/apps/any/spaces) provides tools for monitoring and managing collaborative spaces across your application that is specific to [Ably Spaces](/docs/spaces). + +## Spaces + +The spaces section lists all active spaces with their member counts. Use the search box to filter spaces by name. Click the inspect button on any space to view detailed information about that space, along with a live feed of events being published to it. + +### Space overview + +The space overview provides a realtime view of activity on the space: + +![Spaces inspector interface](../../../../../../images/content/screenshots/dash/spaces1.png) + +This view also includes: + +* Live analytics showing the current rate of messages on the space. +* Any configured [rules](/docs/channels#rules) that apply to the space. +* Any configured [integrations](/docs/integrations) that will run against the space. +* Live logs showing lifecycle events for that space, such as the regions it is active in. + +### Connections + +The connections tab lists all members currently connected to the space. Click **Inspect** on any connection to view details of that [connection](/docs/platform/account/app/connections), including a list of spaces it is connected to. + +## Messages + +The messages tab displays a realtime view of messages and events being published to the space. + +## Presence + +The presence tab displays a realtime view of presence events occurring on the channel, every time a member enters, leaves, or updates their member data. diff --git a/src/pages/docs/platform/account/app/queues.mdx b/src/pages/docs/platform/account/app/queues.mdx index 4503803ca1..23df1ab683 100644 --- a/src/pages/docs/platform/account/app/queues.mdx +++ b/src/pages/docs/platform/account/app/queues.mdx @@ -6,29 +6,33 @@ redirect_from: - /docs/account/app/queues --- -Ably queues provide a way to consume realtime data using the [AMQP](/docs/platform/integrations/queues#consume-amqp) or [STOMP](/docs/platform/integrations/queues#consume-stomp) protocols. Find out more about using [Ably queues](/docs/platform/integrations/queues#what). +Ably queues provide a way to consume realtime data using the [AMQP](/docs/platform/integrations/queues#consume-amqp) or [STOMP](/docs/platform/integrations/queues#consume-stomp) protocols. Manage your queues through the [app dashboard](https://ably.com/accounts/any/apps/any/queues) under the Queues section. Find out more about using [Ably queues](/docs/platform/integrations/queues#what). -## Manage your Ably queues +![Ably queues dashboard interface](../../../../../images/content/screenshots/dash/queues.png) -The Ably queues tab enables you to: +## Manage your Ably queues + +The Ably queues tab enables you to: * Access a list of all your existing queues. * Monitor realtime data flow and queue performance. * Click on any queue to view and adjust its settings, such as TTL, maximum length, and region. -### Provision a new queue +### Provision a new queue + +When provisioning a new queue, you need to specify: -When provisioning a new queue, you'll need to specify several things: +| Field | Description | Type | +| ----- | ----------- | ---- | +| Name | Choose a unique name for your queue. | String | +| Region | Select the geographic region where the queue will be hosted. This is important for optimizing latency and ensuring data residency requirements are met. | String | +| TTL (Time to Live) | Set how long messages remain in the queue before being automatically deleted if they are not consumed. The default account limit is 60 minutes. | Integer | +| Max length | Define the maximum number of messages the queue can hold at any given time. The default limit is 10,000 messages. | Integer | -| Field | Description | -| ----- | ----------- | -| **Name** | Choose a unique name for your queue. This will help you identify it within your dashboard and during application development. | -| **Region** | Select the geographic region where the queue will be hosted. This is important for optimizing latency and ensuring data residency aligns with your application's requirements. | -| **TTL (time to Live)** | Set the TTL, which determines how long messages remain in the queue before being automatically deleted if they are not consumed. The default account limit is 60 minutes. You can contact Ably support for assistance if you need a longer TTL. | -| **Max length** | Define the maximum number of messages the queue can hold at any given time. The default limit is 10,000 messages, but you can request an increase if your application requires more capacity. | +Contact Ably support if you need higher limits for TTL or message capacity. ### Set up queue rules Once you have provisioned a physical queue, you need to set up one or more queue rules to republish messages, presence events or channel events from pub/sub channels into a queue. Queue rules can either be used to publish to internal queues (hosted by Ably) or external external streams or queues (such as Amazon Kinesis and RabbitMQ). Publishing to external streams or queues is part of our [Ably Firehose servers](/docs/platform/integrations/streaming). -Ably queue rules are setup in the **Integrations** tab found within your app **dashboard**. Find out more about setting up [queue rules](/docs/platform/integrations/queues#setup). +Ably queue rules are setup in the "Integrations" tab of your app. Find out more about setting up [queue rules](/docs/platform/integrations/queues#setup). diff --git a/src/pages/docs/platform/account/app/settings.mdx b/src/pages/docs/platform/account/app/settings.mdx deleted file mode 100644 index ef1dc62212..0000000000 --- a/src/pages/docs/platform/account/app/settings.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Settings -meta_description: "Manage your Ably application settings including security, billing, authentication, and protocol support to optimize performance and enhance security." -meta_keywords: "Ably app settings, application management, security settings, two-factor authentication, billing management, protocol support, channel configuration, push notifications" -redirect_from: - - /docs/account/app/settings ---- - -Manage your Ably application settings including security, billing, authentication, and protocol support to optimize performance and enhance security. - -### Application settings overview - -The following provides an overview of your application settings. - -| Section | Description | -| ------ | ------------ | -| **App ID** | This ID is automatically generated by Ably when you create an application. It is a critical part of your application's identity and is included in every API key and token issued for your application. | -| **Name** | This is the user-defined name that you assigned when creating your application. It is helpful for quickly identifying the application among others in your dashboard, especially if you manage multiple applications. | -| **Security** | Enabled by default, this option enforces Transport Layer Security (TLS) for all connections to your application. TLS protocol ensures data encryption and secure communication between clients and servers. | -| **Enabled** | When an application is disabled, it no longer accepts new connections and deactivates all associated services. Clients cannot connect, send or receive messages, or use other Ably services. When enabled, the application allows new connections and activates all related services. | - -### Rule configuration - -The following explains the configuration rules for specific [namespaces](/docs/channels#namespaces) or [channels](/docs/channels): - -| Section | Description | -| ------- | ----------- | -| Namespace or channel ID | Identify the specific namespace or channel to which this rule will apply. | -| Persist last message | Stores the last message published on a channel for 365 days, accessible via the rewind mechanism. | -| Persist all messages | Ably stores all messages for two minutes by default. Depending on your account package, this can be increased to 24 or 72 hours. It is also possible to persist the last message sent to a channel for a year. | -| Identified | Requires clients to authenticate with a client ID to interact with channels in this namespace. | -| TLS only | Restricts access to channels within this namespace to clients connected using TLS. | -| Push notifications enabled | Enables publishing messages with a push payload, triggering native push notifications to registered devices. | -| Message interactions enabled | Enables unique time serial fields in messages, enabling typed references between messages (e.g., implementing 'Likes' in a chat). | -| Server-side batching enabled | Batches inbound messages on the server side before sending them to subscribers based on the configured policy. | -| Cancel | Discards changes and closes the dialog without saving the new rule.| - -### Protocol adapter settings - -The following explains the configuration support for various communication protocols ([Pusher](/docs/protocols/pusher), [PubNub](/docs/protocols/pubnub), [MQTT](/docs/protocols/mqtt)), enabling different client libraries to interact with Ably. - -| Settings | Description | -| --------- | ----------- | -| Pusher protocol support | Provides compatibility with the Pusher protocol. | -| PubNub protocol support | Provides compatibility with the PubNub protocol. | -| MQTT protocol support | Provides compatibility with the MQTT protocol. | - -### Actions - -**Delete this app now** to permanently delete your app including your message history, statistics and prevent access to Ably with any of the API keys assigned to this app. diff --git a/src/pages/docs/platform/account/app/stats.mdx b/src/pages/docs/platform/account/app/stats.mdx deleted file mode 100644 index 9387307bd7..0000000000 --- a/src/pages/docs/platform/account/app/stats.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Stats -meta_description: “Monitor and analyze your app's performance with Ably's dashboard. Access realtime stats and trends for optimized management." -meta_keywords: "Ably dashboard, dashboard, app performance, realtime stats, usage monitoring, performance analysis, data trends, statistics chart, statistics table" -redirect_from: - - /docs/account/app/stats ---- - -The stats tab is an interface to monitor your app's performance and usage via the [statistics table](#table) and [statistics chart](#chart). - -## Statistics table - -The statistics table provides a summary of your app's messaging and data usage patterns over different time frames, including the previous month, the current month, and more granular insights from the last hour and last minute: - -![Your stats table](../../../../../images/content/screenshots/dash/stats-table.png) - -The following explains the statistics table metrics: - -| Metric | Description | -|--------|-------------| -| Messages (billable) | Total number of messages used. | -| Messages published (REST & Realtime) | Number of messages sent via REST and Realtime. | -| Messages received (Realtime) | Number of messages received. | -| Messages persisted (history) | Number of messages retrieved from history. | -| Messages retrieved (history) | Number of messages retrieved from history. | -| Presence events (REST & Realtime) | Number of presence-related events via REST and Realtime. | -| Webhook / Function | Number of messages transferred through functions and webhooks. | -| Ably Queue | Number of messages transferred through queues. | -| Firehose | Number of messages transferred through Firehose. | -| Push notifications | Number of push notifications sent. | -| Data transferred | Amount of data transferred, in bytes. | -| Peak connections | Highest number of concurrent connections. | -| Peak channels | Highest number of concurrent channels. | - - - -## Statistics chart - -The Stats page also includes a chart that visualizes your app's data over time: - -![Your stats chart](../../../../../images/content/screenshots/dash/stats-chart.png) - -The following explains how to use the statistics chart: - -* **Duration**: Define a specific time range for the statistics you want to view. This enables you to focus on periods of particular interest. For example, set the time range from "2024-06-17 00:00" to "2024-08-06 11:18" to analyze data within that period. -* **Zoom**: Use preset zoom options (1h, 8h, 24h, 7d, 1m, 6m, 1y, all) to adjust the chart's view to different periods, enabling you to analyze data at various granularities. diff --git a/src/pages/docs/platform/account/control-api.mdx b/src/pages/docs/platform/account/control-api.mdx index 8f7ceb42a6..bbf03ab6b3 100644 --- a/src/pages/docs/platform/account/control-api.mdx +++ b/src/pages/docs/platform/account/control-api.mdx @@ -11,6 +11,8 @@ redirect_from: 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](/docs/api/control-api). +Access your [account dashboard](https://ably.com/accounts/any) to view the apps and resources you can manage with the Control API. + 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: @@ -26,7 +28,7 @@ Repetitive operations such as creating, updating or deleting Ably apps, enumerat The following diagram illustrates an example use case: -![Provision and Test](../../../../images/content/screenshots/control-api/provision-and-test.png) +![Control API programmatic management interface](../../../../images/content/screenshots/dash/programmatic-man.png) In this use case, Control API is used to provision a sample app for review and testing purposes. Once provisioned, the [realtime](/docs/api/realtime-sdk) or [REST API](/docs/api/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. @@ -46,13 +48,11 @@ Using the code-generation capabilities of tools such as [Postman](https://www.po 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](https://ably.com/accounts/any), on the top menu bar, select your account from the dropdown list and then select **My Access Tokens** from the menu: - -![My Settings](../../../../images/content/screenshots/control-api/my-access-tokens-menu-item.png) +In the [Ably dashboard](https://ably.com/accounts/any), select **Personal access tokens** from the user profile dropdown: You are presented with the **My Access Tokens** area, where you can create tokens for use with the Control API: -![My Settings](../../../../images/content/screenshots/control-api/my-access-tokens.png) +![Access token management interface](../../../../images/content/screenshots/dash/access-token.png) ### Creating an access token @@ -62,7 +62,7 @@ To create a new token, click the **Create new access token** button. Then enter 2. Select the capabilities you wish the token to have, depending on your use case. 3. Click the **Create** button to create the token. -![My Settings](../../../../images/content/screenshots/control-api/new-access-token.png) +![Access token creation dialog](../../../../images/content/screenshots/dash/access-token-set.png) ### Using the access token @@ -126,13 +126,11 @@ Operations that affect your entire account, such as [listing the apps](/docs/api ### How to find your account ID -In the [Ably dashboard](https://ably.com/accounts/any), on the top menu bar, select your account from the dropdown list and then select **Account settings**: - -![Account Settings](../../../../images/content/screenshots/control-api/account-settings-menu-item.png) +In the [Ably dashboard](https://ably.com/accounts/any), navigate to the **Settings** section in the sidebar. Your account settings are displayed. From here you can obtain your Ably account ID, as shown in the following screenshot: -![Account ID](../../../../images/content/screenshots/control-api/account-id.png) +![Account ID in dashboard settings](../../../../images/content/screenshots/control-api/account-id.png) You'll need your account ID for account-level Control API requests, such as listing all the apps in your Ably account. @@ -210,12 +208,12 @@ Sample response, with `entries` trimmed for readability: 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](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html) info -* Retrieve app statistics +* Get a list of apps. +* Create an app. +* Update an app. +* Delete an app. +* Update an app's [APNs](https://developer.apple.com/library/archive/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/APNSOverview.html) info. +* Retrieve app statistics. #### Create an app @@ -342,9 +340,9 @@ Sample response, with `entries` trimmed for readability: You can use the Control API to manage [Ably queues](/docs/platform/integrations/queues). The main operations are: -* List all Ably queues -* Create a queue -* Delete a queue +* List all Ably queues. +* Create a queue. +* Delete a queue. #### List queues @@ -458,10 +456,10 @@ Sample response: 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 +* 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](/docs/auth/capabilities) for different channels. @@ -615,11 +613,11 @@ In this case there is only a status code returned (200), or an error code. You can use the Control API to manage Ably [integration rules](/docs/platform/integrations). 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 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 diff --git a/src/pages/docs/platform/account/enterprise-customization.mdx b/src/pages/docs/platform/account/enterprise-customization.mdx index 92197df19d..fcc16822dc 100644 --- a/src/pages/docs/platform/account/enterprise-customization.mdx +++ b/src/pages/docs/platform/account/enterprise-customization.mdx @@ -9,10 +9,10 @@ redirect_from: If you're an [Ably Enterprise](https://ably.com/pricing) customer, then you can optionally create a **custom endpoint** to tailor the Ably platform to your specific requirements. A custom endpoint enables you to benefit from the following: -* **Active traffic management**: Let Ably actively monitor not only the global cluster health but also your own domains and proactively take steps to isolate or move traffic to ensure business continuity. -* **Dedicated, isolated clusters**: Rely upon guaranteed capacity and isolation from noisy neighbors. -* **Regional routing of traffic**: Require that all traffic is routed and serviced within specific regions. -* **Regional message storage**: Require that all messages are stored within a specific region. +* Active traffic management - Let Ably actively monitor not only the global cluster health but also your own domains and proactively take steps to isolate or move traffic to ensure business continuity. +* Dedicated, isolated clusters - Rely upon guaranteed capacity and isolation from noisy neighbors. +* Regional routing of traffic - Require that all traffic is routed and serviced within specific regions. +* Regional message storage - Require that all messages are stored within a specific region. A custom endpoint provides you with an option to service Ably platform requests. These can be either subdomains of `ably.net`, or point at your own custom CNAME domain. If you choose the latter option, Ably can also customize our client library SDKs to use your chosen domain and make them available via our CDN as `cdn.ably.com/lib/yourcompany.min.js`. @@ -38,9 +38,9 @@ We provide you with a custom endpoint for your cluster, for example: `yourcompan Please note the following: -* Ably only supports Amazon EC2 environments (within Virtual Private Networks) -* Ably is responsible for pro-actively managing and updating dedicated clusters -* Dedicated clusters can run in one or more regions of your choice +* Ably only supports Amazon EC2 environments (within Virtual Private Networks). +* Ably is responsible for pro-actively managing and updating dedicated clusters. +* Dedicated clusters can run in one or more regions of your choice. If you would like to find out more about our dedicated cluster offering, please [get in touch](https://ably.com/contact). @@ -65,7 +65,7 @@ This approach does not apply regional restrictions when you are using a persiste To use a custom endpoint, perform the following steps: -### Decide whether to use an Ably subdomain, or your own domain +### Decide whether to use an Ably subdomain, or your own domain Ably client libraries connect to the `main.realtime.ably.net` domain by default. This domain is used by both WebSocket and other realtime connections from the Ably client libraries, as well as all REST-based requests. It is optimized for all standard HTTP-based request types, including all [REST requests](/docs/api/rest-api), [authentication requests](/docs/auth), and Comet and JSONP fallback when WebSockets cannot be used. @@ -99,7 +99,7 @@ In addition, Ably handle all certificate renewals, rolling out to our global end When using your own custom domain, Ably provide these DNS records for you to CNAME to. Although it is recommended that you implement a similar architecture by using CNAMEs under two different domains (for example, `ably.example.com` for your primary traffic and `ably.fallback-example.com` for your fallback traffic, with the latter hosted with a different registrar and using different name servers to the first), this is not mandatory. Therefore, the decision as to whether you need that extra level of redundancy within your own DNS system is yours. -### Request a custom endpoint +### Request a custom endpoint To enable a custom endpoint for your enterprise, speak to your customer success manager. They will create the custom endpoint for you and provide you with a `ClientOptions` object, containing the following options for the `endpoint` property: @@ -107,7 +107,7 @@ To enable a custom endpoint for your enterprise, speak to your customer success * `endpoint=main` routes to `main.realtime.ably.net` * `endpoint=example-eu` routes to `example-eu.realtime.ably.net` -### Test the custom endpoint +### Test the custom endpoint Test your custom endpoint by visiting it. The URL for your endpoint will depend on whether you have opted to use an Ably subdomain or a custom CNAME domain. @@ -153,7 +153,7 @@ You should then test that all client SDKs can connect, publish, and receive mess Where possible, you should also inspect your network traffic to verify that the client SDKs are calling the endpoints for your custom endpoint. Instead of connections to `realtime.ably.net` you should see connections to `[ENDPOINT].realtime.ably.net`, or your own custom CNAME domain. -### Roll out your changes +### Roll out your changes Once all your client library SDKs are using the new endpoint and traffic is arriving at the correct endpoints, the team at Ably will be able to actively reroute your traffic based on your endpoint settings. diff --git a/src/pages/docs/platform/account/index.mdx b/src/pages/docs/platform/account/index.mdx index 98b7715222..9527c1e7ac 100644 --- a/src/pages/docs/platform/account/index.mdx +++ b/src/pages/docs/platform/account/index.mdx @@ -1,71 +1,49 @@ --- title: Account overview -meta_description: "Manage all aspects of your account, from 2FA and billing to user management and personal preferences. " -meta_keywords: "Ably account, 2FA, billing, user management, personal preferences" +meta_description: "Overview of the Ably dashboard for managing apps, account settings, team, billing, and usage." +meta_keywords: "Ably dashboard, account settings, team management, billing, limits, reports" redirect_from: - /docs/account --- -Manage all aspects of your account, from Two-factor authentication ([2FA](/docs/platform/account/2fa)) and billing to user management and personal preferences. +The [Ably dashboard](https://ably.com/accounts) is where you manage your accounts and apps. -Begin by [logging](https://ably.com/login) in to Ably through your browser. Once you're logged in, you have access to the Ably dashboard, where you can click on the Account navigation dropdown to access the account settings: +## Apps -![Ably Account Settings](../../../../images/content/screenshots/dash/account.png) +Select an [app](/docs/platform/account/app), or create a new one to get started with Ably. -### Settings +## Account settings -Manage your Ably account settings, including authentication, [billing](/docs/platform/pricing/billing), and account ownership: +Use your [account settings](https://ably.com/accounts/any/settings) to view your `Account ID` and manage your [organizations](/docs/platform/account/organizations). -* Use your account's unique identifier (Account ID) when contacting support. -* Account owners can require all users to set up two-factor authentication (2FA) for added security. -* Account owners and users with the billing role can update billing and package details. They are the only users who can modify these settings or transfer account ownership. -* Transfer ownership or cancel the account, contact [Ably support.](https://ably.com/support) +Account owners can also transfer the ownsership of an account to another user, or delete the account entirely. Both of these operations are permanent and can't be undone. -### Billing +## Security -Manage your [billing](/docs/platform/pricing/billing) and package settings to scale your services: +Use [account security](https://ably.com/accounts/any/security) to enforce [2FA](/docs/platform/account/2fa) for all users in your account, and to setup [SSO](/docs/platform/account/sso). -* Review your current package to assess if it fits your needs, whether free, pay-as-you-go, or committed use. -* Ensure your billing information is up to date, including company name, billing email (optional), address, international phone number, and timezone. -* View and manage invoices and payment methods once your account has been upgraded. +## Team -### Limits +Use the [teams page](/docs/platform/account/team) to manage who has access to your Ably account. You can invite add and remove new users, and manage their [roles](/docs/platform/account/team#roles). -Understand and manage your package [limits](/docs/platform/pricing/limits) by tracking usage across messages, data, connections, and channels: +## Package -* Limits are applied to prevent service disruption and vary by package. -* Limits can be time-based, quantity-based, or rate-based, and they may apply either per connection/channel or across the entire account. -* Notifications are provided when limits are nearing or exceeded, and detailed logs of warnings and exceeded limits are accessible in the account dashboard. +Use the [package page](https://ably.com/accounts/any/package) to manage your [subscription](/docs/platform/pricing). You can upgrade and downgrade between packages. -### Usage +Only the account owner can access the package page. -Monitor your account's resource consumption with detailed usage statistics: +## Invoices -* The usage statistics table monitors app performance by tracking resource usage, such as messages, data transferred, connections, and channels. -* The statistics chart visualizes app usage data over time, allowing users to define specific time ranges, zoom in on different periods, and analyze metrics in detail. +Use the [invoices page](https://ably.com/accounts/any/package#invoices) to view and download your invoices. -### Users +## Usage -Manage the [users](/docs/platform/account/users) associated with your account: +Use the [usage page](https://ably.com/accounts/any/reports/billable_consumption_summary) to view details of your current and historic usage across your account. This includes message consumption, and connection and channel minutes used. -* The account owner role has full permissions to manage the account, including inviting and removing users, and assigning roles like developer, billing, or admin. -* Multiple roles can be assigned to a single user. -* Remove, or change user roles within an Ably account. +## Limits -### My Settings +Use the [limits page](https://ably.com/accounts/any/package_limits) to view the limits set for your account. -Control personal account settings: +## Reports -* View and edit name, email, and password. -* Enable two-factor authentication (2FA) for added security. -* Connect and manage login providers (Google, GitHub). -* Customize Ably email preferences (product updates, news, educational emails) -* Set up notifications for account usage. - -### My Access tokens - -Create access tokens for the [Control API:](/docs/platform/account/control-api) - -* Users can create new tokens by providing a descriptive name, assigning an account, selecting capabilities, and securely storing the token once generated. -* Users can revoke existing tokens through the settings section, but this action is irreversible and will immediately invalidate the token for API access. -* After a token is created, the full token cannot be viewed again, so it must be securely stored upon generation. +The [reports section](https://ably.com/accounts/any/reports) provides access to the reports dashboard, where you can select and view reports about your account. diff --git a/src/pages/docs/platform/account/organizations.mdx b/src/pages/docs/platform/account/organizations.mdx index d71d54dc45..94680e8b2a 100644 --- a/src/pages/docs/platform/account/organizations.mdx +++ b/src/pages/docs/platform/account/organizations.mdx @@ -8,6 +8,8 @@ redirect_from: Use organizations to manage multiple Ably accounts by centralizing user access and roles under a single organizational structure. Organizations streamline user provisioning through [Single Sign-On (SSO)](/docs/platform/account/sso) configuration and utilize SCIM System for Cross-domain Identity Management for group-based access control. +Access your [organization settings](https://ably.com/accounts/any/organization) to manage your organization configuration and user access. + Organizations enable the [primary](#primary) account to assign and adjust the roles of users and groups across all accounts. You can separate accounts within an organization to create isolated environments, such as production, staging, and development. Assign each environment a [package](/docs/platform/pricing#packages) that meets its specific needs. For example, production may need high capacity with an **Enterprise** package, staging might use a **Standard** package, and development a **Free** package. @@ -21,17 +23,17 @@ An [Enterprise](/docs/platform/pricing/enterprise) account is required to use or The primary account is an organization's main account and holds the following privileges: * The highest level of access to the organization. -* Ownership of all all accounts within the organization. +* Ownership of all accounts within the organization. * The default account used for provisioning. ## Create accounts in an organization Create accounts in an organization: -* Open the **Account** navigation dropdown. - * Click **Organization Accounts.** - * Click **New account**. - * Add an account name and **Create account**. +1. Open the **Account** navigation dropdown. +2. Click **Organization Accounts**. +3. Click **New account**. +4. Add an account name and **Create account**. ## Provision users via SCIM @@ -47,22 +49,21 @@ Ably only recognizes one registered email domain per organization, unrecognized Users provisioned through SCIM cannot modify their name or email address within Ably. All personal information updates must be made through your identity provider, and changes will sync to Ably on the next SCIM update cycle. -The following steps outline the process for provisioning users through SCIM: - -* Configure [SSO](/docs/platform/account/sso) by enabling and setting up SSO between Ably and your identity provider. +Provision users through SCIM: -* Copy Ably SCIM configuration values: - * Open the **Account** navigation dropdown in the Ably dashboard. - * Select **Organization Settings** from the menu. - * Navigate to the **Users & Groups Provisioning (SCIM)** section and copy: - * **Service Provider Configuration Endpoint.** - * **SCIM Username.** - * **SCIM Password.** -* In your identity providers provisioning app, paste the following values from Ably: - * **Service Provider Configuration Endpoint.** - * **SCIM Username.** - * **SCIM Password.** -* Ensure that any additional setup required by your identity provider is completed to finalize the SCIM configuration. +1. Configure [SSO](/docs/platform/account/sso) by enabling and setting up SSO between Ably and your identity provider. +2. Copy Ably SCIM configuration values: + 1. Open the **Account** navigation dropdown in the Ably dashboard. + 2. Select **Organization Settings** from the menu. + 3. Navigate to the **Users & Groups Provisioning (SCIM)** section and copy: + * **Service Provider Configuration Endpoint**. + * **SCIM Username**. + * **SCIM Password**. +3. In your identity providers provisioning app, paste the following values from Ably: + * **Service Provider Configuration Endpoint**. + * **SCIM Username**. + * **SCIM Password**. +4. Ensure that any additional setup required by your identity provider is completed to finalize the SCIM configuration. ## Manage roles @@ -73,12 +74,13 @@ Manage user and group [roles](/docs/platform/account/users#roles) across account When organizations and your identity provider are configured, the groups you create in the identity provider are synchronized with Ably. This enables you to manage group-based access centrally. Assign roles to these groups across one or more accounts. When a group is linked to an account, all users in that group are automatically provisioned into that account and inherit the assigned roles. Users added to the group afterwards are also provisioned into the linked accounts automatically. -To manage group roles in Ably: -* Open the **Account** navigation dropdown. - * Click **Organization Users**. - * Under **Ably Realtime identity provider groups**, click **Manage account access**. - * Select the group whose access you want to manage. - * Specify the required **Roles** for the group -- and all users in this group inherit these roles automatically. +Manage group roles in Ably: + +1. Open the **Account** navigation dropdown. +2. Click **Organization Users**. +3. Under **Ably Realtime identity provider groups**, click **Manage account access**. +4. Select the group whose access you want to manage. +5. Specify the required **Roles** for the group -- and all users in this group inherit these roles automatically. -The Ably CLI brings the full power of Ably to your terminal. You can use it to manage your Ably account and its resources, and to explore Ably's APIs and features. +The Ably CLI brings the full power of Ably to your terminal. You can use it to manage your Ably account and its resources, and to explore Ably's APIs and features. The same capabilities are also available in the CLI section of the [Ably dashboard](https://ably.com/accounts/any/apps/any/). + +![Ably CLI interface](../../../../images/content/screenshots/dash/cli.png) It's a quick and easy way to simulate additional clients when testing how Ably works. diff --git a/src/pages/docs/storage-history/history.mdx b/src/pages/docs/storage-history/history.mdx index c49c49cb12..69ab870c0c 100644 --- a/src/pages/docs/storage-history/history.mdx +++ b/src/pages/docs/storage-history/history.mdx @@ -887,7 +887,7 @@ Understanding these synchronization characteristics helps you design robust appl * History requests may show slight delays (up to 100ms) for messages published in remote datacenters. * Connection recovery works reliably regardless of datacenter failover. * Message continuity is preserved even during regional failures. -* Applications should not depend on instant global history consistency for real-time features. +* Applications should not depend on instant global history consistency for realtime features. ## Ordering of historical messages