diff --git a/content/account/2fa.textile b/content/account/2fa.textile deleted file mode 100644 index 2acc44cb8b..0000000000 --- a/content/account/2fa.textile +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: Two-factor authentication (2FA) -meta_description: "Enable two-factor authentication for your Ably account." -meta_keywords: "2FA, two-factor, authentication, MFA" ---- - -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. - -h2(#enable). 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. -** 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. - -h3(#disable). 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. -** Re-enter your password as prompted. - -h3(#phone). Change phone number - -Disable and re-enable 2FA in order to update your phone number. - -h3(#sms). SMS and TOTP 2FA - -Disable and re-enable 2FA in order to switch between SMS 2FA and TOTP (time-based one-time password) 2FA. - -h2(#enforce). Enforce 2FA for all users - -"Account owners":/docs/account/users can require 2FA to be utilized by all users. Any user that hasn't already enabled 2FA will be prompted to do so the next time they attempt to access the account. - - - -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. - -h3(#remove). 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. diff --git a/content/account/app/api.textile b/content/account/app/api.textile deleted file mode 100644 index 8a77d8cff8..0000000000 --- a/content/account/app/api.textile +++ /dev/null @@ -1,52 +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" ---- - -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. - -h2(#create). 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. - -h3. 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 channel rules. | - -h3. 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. | - -h3. 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. | - -h3. 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/content/account/app/console.textile b/content/account/app/console.textile deleted file mode 100644 index 1b00af07e2..0000000000 --- a/content/account/app/console.textile +++ /dev/null @@ -1,60 +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" ---- - -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. - -h2. 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. | - -h2. Channels - -The following is a step-by-step instructions for connecting to a channel, publishing messages. - -h3. 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.| - -h3. 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*. | - -h3. 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/content/account/app/notifications.textile b/content/account/app/notifications.textile deleted file mode 100644 index 4403aa9470..0000000000 --- a/content/account/app/notifications.textile +++ /dev/null @@ -1,70 +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" ---- - -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. - -h3(#configure-FCM). 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. - -h3(#configure-APNs). 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*. - -h2. 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. - -h3. API key - -The "API Key":/docs/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. - -h3. 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. | - -h3. 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. | - -h2. 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 your Ably account. | Click *inspect client ID* to see detailed information about a specific client, including its subscriptions and recent activity. | diff --git a/content/account/app/queues.textile b/content/account/app/queues.textile deleted file mode 100644 index adcb15a240..0000000000 --- a/content/account/app/queues.textile +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Queues -meta_description: Manage and configure Ably queues, monitor realtime data, and optimize performance.” -meta_keywords: “Ably Queues, realtime data, AMQP, STOMP, queue management, TTL, queue settings" ---- - -Ably queues provide a way to consume realtime data using the "AMQP":/docs/integrations/queues#consume-amqp or "STOMP":/docs/integrations/queues#consume-stomp protocols. Find out more about using "Ably queues":/docs/integrations/queues#what. - -h2. 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. - -h3. Provision a new queue - -When provisioning a new queue, you'll need to specify several things: - -|_. 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. | - -h3(#setup). 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/general/firehose. - -Ably queue rules are setup in the *Integrations* tab found within your app *dashboard*. Find out more about setting up "queue rules":/docs/integrations/queues#setup. diff --git a/content/account/app/settings.textile b/content/account/app/settings.textile deleted file mode 100644 index 74e4cfdc2c..0000000000 --- a/content/account/app/settings.textile +++ /dev/null @@ -1,45 +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" ---- - -Manage your Ably application settings including security, billing, authentication, and protocol support to optimize performance and enhance security. - -h3. 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. | - -h3. Channel 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.| - -h3. 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. | - -h3. 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/content/account/app/stats.textile b/content/account/app/stats.textile deleted file mode 100644 index 6f97f0dc86..0000000000 --- a/content/account/app/stats.textile +++ /dev/null @@ -1,51 +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" ---- - -The stats tab is an interface to monitor your app's performance and usage via the "statistics table":#table and "statistics chart":#chart. - -h2(#table). 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 - - -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. | - - - -h2(#chart). Statistics chart - -The Stats page also includes a chart that visualizes your app's data over time: - - - Your stats chart - - -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/content/account/organizations.textile b/content/account/organizations.textile deleted file mode 100644 index e34d89cecd..0000000000 --- a/content/account/organizations.textile +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Organizations -meta_description: "Manage Ably organizations, provision users, configure SSO with SCIM, and handle account roles." -meta_keywords: "Ably organizations, user provisioning, SSO, SCIM, access management, Ably dashboard, account roles" ---- - -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/account/sso configuration and utilize SCIM System for Cross-domain Identity Management for group-based access control. - -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/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. - - - -h2(#primary). Primary account - -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. -* The default account used for provisioning. - -h2(#accounts). 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*. - -h2(#scim). Provision users via SCIM - - - -Manage access to multiple Ably accounts through a single identity provider. To enable this, configure both "SSO":/docs/account/sso with your chosen identity provider and "SCIM":#SCIM. Once configured, Ably automatically provisions and deprovisions users with access to the Ably app in your identity provider, either individually or through assigned groups. New users are added to Ably's default provisioning account with the role of *Developer*. - -Ably only recognizes one registered email domain per organization, unrecognized email domains will result in rejected provisioning attempts. - -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/account/sso by enabling and setting up SSO between Ably and your identity provider. - -* 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. - - -h2(#manage). Manage roles - -Manage user and group "roles":/docs/account/users#roles across accounts within your organization. User and group roles include those assigned directly to the user and through the groups the user belongs to. Use the *Organization Users* page as a central point of control, rather than managing access individually within each account. - -h3(#group). Group roles - -When organizations and your identity provider are configured, the groups you create in the identity provider are synchronized with Ably. This allows you to manage group-based access centrally. Assign roles to these groups and all users in a group will inherit those roles. - -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. - - diff --git a/content/account/sso.textile b/content/account/sso.textile deleted file mode 100644 index a24ca16eaf..0000000000 --- a/content/account/sso.textile +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Single sign-on (SSO) -meta_description: "Single sign-on enables users to authenticate with Ably using your own identity provider." -meta_keywords: "sso, saml, strict mode, single sign-on" ---- - -Single sign-on (SSO) enables your users to authenticate via any SAML-compatible identity provider. - -h2(#configure). Configure - -Single sign-on is restricted to Enterprise customers only and must be enabled on a per-account basis by "contacting Ably":https://ably.com/contact. Only "account owners":/docs/account/users can configure SSO for an account. - -Any SAML-compatible identity provider can be used to enable SSO. - -The following instructions are examples of configuring SSO with "Okta":#okta and "Google Workspace":#google. - -h3(#okta). Okta - -To enable SSO using "Okta":https://www.okta.com/ as the identity provider, configure the following properties in your Ably account dashboard and your Okta account: - -In your Ably account dashboard: - -1. Log in to your "account":https://ably.com/accounts/any. -2. Select *Settings* from the account navigation dropdown. -3. Toggle *Enable Single Sign-On* under the *Authentication Settings* section. -4. Note down the *Single sign-on URL* and *Audience URI* values. - -In your Okta account: - -Use the "Okta guide":https://developer.okta.com/docs/guides/saml-application-setup/overview/ for enabling SSO. - -1. Upload the Ably logo. -2. Select *EmailAddress* for the *Name ID format* field. -3. Select *Email* for the *Application username* field. -4. Ably requires users' full names, so ensure *first_name* and *last_name* are populated. -5. Assign users to the newly created Okta application. -6. Note down the *Identity Provider metadata* from Okta. - -In your Ably account dashboard: - -1. Log in to your "account":https://ably.com/accounts/any. -2. Select *Settings* from the account navigation dropdown. -3. Complete the SSO fields with the values obtained from Okta: -** *Identity Provider Single Sign-On URL* -** *Identity Provider Issuer* -** *X.509 Certificate* -4. *Save* the authentication settings. - -h3(#google). Google Workspace - -To enable SSO using "Google Workspace":https://workspace.google.com/ as the identity provider, configure the following properties in your Ably account dashboard and your Google Workspace: - -In your Ably account dashboard: - -1. Log in to your "account":https://ably.com/accounts/any. -2. Select *Settings* from the account navigation dropdown. -3. Toggle *Enable Single Sign-On* under the *Authentication Settings* section. -4. Note down the *Single sign-on URL* and *Audience URI* values. - -In your Google Workspace account: - -Use the "Google Workspace guide":https://support.google.com/a/answer/6087519?hl=en for enabling SSO. - -1. Upload the Ably logo. -2. Copy and paste the metadata configuration into your Ably account: -** *Identity Provider Single Sign-On URL* -** Use *Entity ID* from Google Workspace as the *Identity Provider Issuer* in your Ably account. -** *X.509 Certificate* -3. *Save* the authentication setting changes in your Ably account. -4. Copy and paste the SAML settings from your Ably account into Google Workspace: -** Use *Single sign on URL* from your Ably account as the *ACS URL* in Google Workspace. -** Use *SP Entity Id* from your Ably account as the *Entity ID* in Google Workspace. -** Use *Entity ID* from Google Workspace as the *Identity Provider Issuer* in your Ably account. -** Select *EMAIL* for the *Name ID format* field. -** Select *Basic Information > Primary Email* for the *Name ID* field. -5. Ably requires users' full names, so ensure *first_name* and *last_name* are populated. -6. Assign users to the newly created Google Workspace application. -7. Test the SSO connection from Google Workspace. - - - -h2(#strict). Strict mode - -Strict mode can be enabled to restrict access to your Ably account to only those users that authenticate with your identity provider. Users that attempt to log in using another method, such as their email address and password or a GitHub log in will be prompted to re-authenticate with your identity provider. - -Strict mode ensures that Ably account access is handled by your identity provider. If a user is removed from your identity provider they will no longer be able to access the Ably account once their current session expires. - - - -To enable strict mode: - -1. Log in to your "account":https://ably.com/accounts/any. -2. Select *Settings* from the account navigation dropdown. -3. Toggle *Enable Strict Mode* under the *Authentication Settings* section. This setting is only visible if SSO has been enabled. diff --git a/content/account/users.textile b/content/account/users.textile deleted file mode 100644 index 21137087b3..0000000000 --- a/content/account/users.textile +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: User management -meta_description: "Learn how to manage users, user roles, and the permissions associated with each role." -meta_keywords: "users, user management, admin, owner, permission" ---- - -The user that creates an Ably account is assigned the account owner role. An account owner has permission to undertake any action within an account, such as inviting new users. There are two other account roles that inherit a subset of an account owner's permissions. An account can only have a single account owner. - -h2(#roles). User roles - -Users can be assigned to the following roles. Each user may be assigned multiple roles: - -* Developer -* Billing -* Admin -* Owner - -User roles have the following permissions: - -|_. Permission |_. Developer |_. Billing |_. Admin |_. Owner | -| View all apps | ✓ | ✓ | ✓ | ✓ | -| View app configuration | ✓ | - | ✓ | ✓ | -| View app settings | ✓ | - | ✓ | ✓ | -| View "app statistics":/docs/metadata-stats/stats#app | ✓ | ✓ | ✓ | ✓ | -| View "account statistics":/docs/metadata-stats/stats#account | ✓ | ✓ | ✓ | ✓ | -| Configure own "2FA":/docs/account/2fa | ✓ | - | ✓ | ✓ | -| "Invite new users":#invite | - | - | ✓ | ✓ | -| "Remove existing users":#remove | - | - | ✓ | ✓ | -| Manage "API keys":/docs/auth | - | - | ✓ | ✓ | -| Manage app configuration | - | - | ✓ | ✓ | -| Manage app settings | - | - | ✓ | ✓ | -| Create apps | - | - | ✓ | ✓ | -| Receive "limit notifications":/docs/pricing/limits | - | - | ✓ | ✓ | -| Configure "single sign-on":/docs/account/sso | - | - | - | ✓ | -| Enforce "2FA":/docs/account/2fa#enforce | - | - | - | ✓ | -| View invoices | - | ✓ | - | ✓ | -| Update billing information | - | ✓ | - | ✓ | -| Manage "account package":https://ably.com/pricing | - | - | - | ✓ | - -h3(#change). Change user roles - -The following steps add or remove roles from a user within an Ably account. You must be an account owner or admin to change user roles: - -1. Log in to your "account":https://ably.com/accounts/any. -2. Select *Users* from the account navigation dropdown. -3. Click the checkboxes corresponding to the roles you want to add or remove. - - - -h2(#invite). Invite a new user - -The following steps invite a new user to your account. You must be an account owner or admin to invite new users: - -1. Log in to your "account":https://ably.com/accounts/any. -2. Select *Users* from the account navigation dropdown. -3. Click *Invite new user*. -4. Enter the user's first name and email address, then click *Invite*. -5. The user can then follow the instructions emailed to them to join your account. - - - -h2(#remove). Remove users from an account - -The following steps remove a user from your account. You must be an account owner or admin to remove users: - -1. Log in to your "account":https://ably.com/accounts/any. -2. Select *Users* from the account navigation dropdown. -3. Click the *Remove* button next to the user to remove them from the account. -4. Confirm the action when prompted. - -h2(#leave). Delete your profile or leave an account - -The following steps delete your profile or remove yourself from an Ably account: - -1. Log in to your "account":https://ably.com/accounts/any. -2. Go to "My Settings":https://ably.com/users/edit. -3. "Disconnect SSO provider":#sso if you use SSO to log in. -4. Scroll to *"Want to delete your profile?"* -5. Click *Start* to remove yourself from this account. - - - -h2(#close). Close your account - -To close your Ably account, you must be the account owner and have downgraded to the Free package. The following steps outline the process to close your account: - -* Log in to your "Ably account":https://ably.com/accounts/any. -* Confirm that you are the "account owner":/docs/account/users#roles. -* "Downgrade your current package":/docs/pricing/free#downgrade to the "Free package":/docs/pricing#packages. - - - -* "Disconnect SSO provider":#sso if you use SSO to log in. -* Go to your "My Settings":https://ably.com/users/edit page. -* Scroll to *Want to delete your profile?* - - - -* Click *Start* to proceed with permanently closing your account. -* On the proceeding *Close Your Ably Account* page, review the accounts for closure. -* Click *Close Account* to permanently deactivate your account. - -h3(#sso). Disconnect SSO provider - -If you use SSO (Single Sign-On) to log in to your Ably account, you must first set a password and disconnect your SSO provider before closing your account. The self-service account closure process requires a password to authenticate the closure request. The following steps set a password and disconnect your SSO provider: - -* Log in to your "account":https://ably.com/accounts/any using your current SSO method (Google or GitHub). -* Navigate to *Account* then "My Settings.":https://ably.com/users/edit -* In the *Password* section, click *Change your password*. -* Click *Update my personal settings* to save the changes. -* Scroll to the *Login provider* section. -* Click *remove connection* next to the SSO provider/s you want to disconnect. -* After completing these steps, return to the instructions above to "close your account":#close. diff --git a/content/api/index.textile b/content/api/index.textile index 7eb0d269c6..2717058a82 100644 --- a/content/api/index.textile +++ b/content/api/index.textile @@ -74,4 +74,4 @@ In addition to the API references listed previously, our developer documentation * "Realtime and REST interface use cases":/docs/realtime#realtime-vs-rest * "REST API - Overview":/docs/rest-api * "SSE API - Overview":/docs/protocols/sse -* "Control API - Overview":/docs/account/control-api +* "Control API - Overview":/docs/platform/account/control-api diff --git a/content/api/realtime-sdk/channels.textile b/content/api/realtime-sdk/channels.textile index e60eb851da..58ff0933fe 100644 --- a/content/api/realtime-sdk/channels.textile +++ b/content/api/realtime-sdk/channels.textile @@ -179,8 +179,8 @@ blang[jsall]. The entire @messages@ array is published atomically. This means that: * Either they will all be successfully published or none of them will -* The "max message size":/docs/pricing/limits#message limit applies to the total size of all messages in the array -* The publish will only count as a single message for the purpose of "per-channel rate limit":/docs/pricing/limits#message +* The "max message size":/docs/platform/pricing/limits#message limit applies to the total size of all messages in the array +* The publish will only count as a single message for the purpose of "per-channel rate limit":/docs/platform/pricing/limits#message * If you are using client-specified message IDs, "they must conform to certain restrictions":https://faqs.ably.com/client-specified-message-id-restrictions-for-multiple-messages-published-atomically h4. Parameters diff --git a/content/api/rest-api.textile b/content/api/rest-api.textile index 4c9e2f2318..454a774b4b 100644 --- a/content/api/rest-api.textile +++ b/content/api/rest-api.textile @@ -1358,7 +1358,7 @@ bc[text]. { * @@ is a single channel name, or an array of up to 100 channel names, expressed as strings. * @@ is a single message, or an array of messages. -The maximum size of each request body must be less than 2MiB and the total size of all messages in a @messages@ array must be less than the "message size limit":/docs/pricing/limits#message (64kiB by default for paid accounts, 16kiB for free accounts). +The maximum size of each request body must be less than 2MiB and the total size of all messages in a @messages@ array must be less than the "message size limit":/docs/platform/pricing/limits#message (64kiB by default for paid accounts, 16kiB for free accounts). Sample request, containing multiple @BatchSpec@ objects in an array: diff --git a/content/api/rest-sdk/channels.textile b/content/api/rest-sdk/channels.textile index f0038c19ce..18bbcfaa98 100644 --- a/content/api/rest-sdk/channels.textile +++ b/content/api/rest-sdk/channels.textile @@ -128,8 +128,8 @@ Publish several messages on this channel. A callback may The entire @messages@ array is published atomically. This means that: * Either they will all be successfully published or none of them will -* The "max message size":/docs/pricing/limits#message limit applies to the total size of all messages in the array -* The publish will only count as a single message for the purpose of "per-channel rate limit":/docs/pricing/limits#message +* The "max message size":/docs/platform/pricing/limits#message limit applies to the total size of all messages in the array +* The publish will only count as a single message for the purpose of "per-channel rate limit":/docs/platform/pricing/limits#message * If you are using client-specified message IDs for publish idempotency, "they must conform to certain restrictions":https://faqs.ably.com/client-specified-message-id-restrictions-for-multiple-messages-published-atomically h4. Parameters diff --git a/content/auth/capabilities.textile b/content/auth/capabilities.textile index 0561a2f9c0..a882eac074 100644 --- a/content/auth/capabilities.textile +++ b/content/auth/capabilities.textile @@ -11,7 +11,7 @@ languages: API keys and Ably-compatible tokens, have a set of capabilities assigned to them that specify which operations (such as subscribe or publish) can be performed on which channels. -API keys are long-lived, secret and typically not shared with clients. API key capabilities are configured using the "dashboard":https://ably.com/dashboard, or using the "Control API":/docs/account/control-api. +API keys are long-lived, secret and typically not shared with clients. API key capabilities are configured using the "dashboard":https://ably.com/dashboard, or using the "Control API":/docs/platform/account/control-api. Ably-compatible tokens are designed to be shared with untrusted clients, are short-lived, and can be configured and issued programmatically. See "selecting an authentication mechanism":/docs/auth#selecting-auth to understand why token authentication is the preferred option in most scenarios. diff --git a/content/auth/index.textile b/content/auth/index.textile index b80c64f78d..185f89938b 100644 --- a/content/auth/index.textile +++ b/content/auth/index.textile @@ -39,7 +39,7 @@ The API key secret is private and should never be made public. This API key stri h3(#create). Create an API key -API keys are created in the "Ably dashboard":https://ably.com/dashboard. You can also create an API key programmatically using the "Control API":/docs/account/control-api. +API keys are created in the "Ably dashboard":https://ably.com/dashboard. You can also create an API key programmatically using the "Control API":/docs/platform/account/control-api. To create an API key in the Ably dashboard: diff --git a/content/channels/options/deltas.textile b/content/channels/options/deltas.textile index 08e78a9fc1..961728124b 100644 --- a/content/channels/options/deltas.textile +++ b/content/channels/options/deltas.textile @@ -185,7 +185,7 @@ If a subscriber has a delta subscription and the channel in question experiences Note that a channel subscriber can experience a discontinuity in the sequence of messages it receives on a given channel for the following reasons: * The connection can drop, and there will be a discontinuity if the client is unable to reconnect within a two-minute window that preserves "connection continuity":/docs/connect/states. -* The outbound connection may become "rate limited":/docs/pricing/limits, which causes some messages to be dropped. +* The outbound connection may become "rate limited":/docs/platform/pricing/limits, which causes some messages to be dropped. * There may have been an internal error in the Ably system leading to the server being unable to preserve continuity on the channel. In these cases, the service indicates the discontinuity to the client, together with the reason, and this is usually visible to the subscriber in a channel @UPDATE@ event. diff --git a/content/connect/index.textile b/content/connect/index.textile index 08bd297adf..9ef679326c 100644 --- a/content/connect/index.textile +++ b/content/connect/index.textile @@ -166,7 +166,7 @@ The 15 second interval between heartbeats is used to strike a balance between op The interval between heartbeats can be customized if your app requires increased battery preservation or to identify dropped connections more quickly. Set a value between 5000 and 1800000 milliseconds (5 seconds and 30 minutes) using the @heartbeatInterval@ parameter within the @transportParams@ property of the "@clientOptions@":/docs/api/realtime-sdk#client-options object. -Using a higher @heartbeatInterval@ can increase the time taken for the Ably service and the client itself to identify a connection has dropped when an abrupt disconnect occurs. The number of "concurrent connections":/docs/pricing/limits#connection may also appear higher as it can take longer to terminate dropped connections. Although @heartbeatInterval@ can be set as high as 30 minutes, Ably does not recommend setting it this high. +Using a higher @heartbeatInterval@ can increase the time taken for the Ably service and the client itself to identify a connection has dropped when an abrupt disconnect occurs. The number of "concurrent connections":/docs/platform/pricing/limits#connection may also appear higher as it can take longer to terminate dropped connections. Although @heartbeatInterval@ can be set as high as 30 minutes, Ably does not recommend setting it this high. You can also call "@ping()@":/docs/api/realtime-sdk/connection#ping to send a heartbeat ping to Ably, which can be useful for measuring the true round-trip latency to the Ably server. @@ -209,7 +209,7 @@ AblyRealtime ably = new AblyRealtime(options); h2(#close). Close a connection -A connection to Ably should be closed once it is no longer needed. Note that there is a 2 minute delay before a connection is closed, if the "@close()@":/docs/api/realtime-sdk/connection#close method hasn't been explicitly called. This is important to consider in relation to the number of "concurrent connections":/docs/pricing/limits#connection to your account. +A connection to Ably should be closed once it is no longer needed. Note that there is a 2 minute delay before a connection is closed, if the "@close()@":/docs/api/realtime-sdk/connection#close method hasn't been explicitly called. This is important to consider in relation to the number of "concurrent connections":/docs/platform/pricing/limits#connection to your account. The following code sample explicitly closes the connection to Ably by calling the @close()@ method and prints the message @Closed the connection to Ably@: diff --git a/content/errors/codes.textile b/content/errors/codes.textile deleted file mode 100644 index 660b324146..0000000000 --- a/content/errors/codes.textile +++ /dev/null @@ -1,794 +0,0 @@ ---- -title: Error codes -meta_description: "Understand Ably error codes and their causes, to resolve them efficiently." -languages: - - javascript ---- - -Use the error codes provided, which include descriptions, possible causes, and solutions, to troubleshoot issues effectively. - - - -h2(#500). 500: Internal error - -This error occurs when there is an issue within Ably's system. - -h2(#5000). 50000: Internal error - -This error occurs when there is an issue within Ably's system. - -h2(#10000). 10000: No error - -This error code indicates that the attempted action was successful and no issues occurred; there will be additional info in the @message@ property about the successful action. - -h2(#20000). 20000: General error code - -This error code is a generic response used when the Ably "protocol":/docs/protocols requires an @errorInfo@ object, even though no actual issue has occurred. The message property may contain additional details about the successful action. - -h2(#40000). 40000: Bad request - -This error occurs when Ably cannot understand the request due to a malformed structure or other issues with the request format. - -An example of this error is when a message is published while the connection is in a "suspended state":/docs/connect/states#connection-states. - -h2(#40001). 40001: Invalid request body - -This error occurs when a request contains invalid content, such as incorrect "data types":/docs/api/realtime-sdk/types#data-types or missing required objects. It is most likely caused by missing required fields or incorrect data formats when sending a request to Ably. - -An example of this error is a missing field, such as a @keyName@ in a "token request":/docs/api/token-request-spec#tokenrequest-format. - -h2(#40003). 40003: Invalid parameter value - -This error occurs when an invalid value is sent in the request. It may be caused by either user input or the SDK sending incorrect parameters. - -Additional examples of the @40003@ error code output include: - -* *40003: Excessive value for TTL* -This error occurs when the "TTL":/docs/api/rest-sdk/authentication#token-request set for a token parameter exceeds the maximum allowed value of 24 hours. -* *40003: Excessive value for TTL (revocation is enabled on this key)* -This error occurs when "revocation":/docs/auth/revocation#revocable-tokens is enabled, revocable tokens are limited to a TTL of 1 hour instead of 24 hours. - -h2(#40005). 40005: Invalid credentials - -This error occurs when the "API key":/docs/auth#api-keys or "token":/docs/auth/token used to initialize the library is invalid. -*Resolution:* The following steps can help resolve this issue: - -* API key initialization: -** Ensure you are the account's *admin* or *owner*. -** In your "Ably dashboard":https://ably.com/accounts/any to the *API keys* tab. -** Use one of these API keys instead of your current one or create a "new API key":/docs/account/app/api#create with the necessary permissions and privileges and use that to instance the SDK. -* Token initialization: -** If you are using "token authentication":/docs/auth/token, ensure you are correctly requesting a valid token before using it with Ably. - -h2(#40006). 40006: Invalid connectionId - -This error occurs when a message is published with an invalid or mismatched "@connectionId@":/docs/messages#properties. - -Examples of this error are when: -* A client attempts to publish a message using a malformed @connectionId@. -* A client publishes a realtime message with a @connectionId@ that does not match the currently active connection. -* A connection is identified, but the resolved @clientId@ is missing or incorrect (due to authentication issues or an explicitly provided, but incorrect, @clientId@). - -h2(#40009). 40009: Maximum message length exceeded - -This error occurs when the message being published exceeds the maximum size allowed set by the "limits":/docs/pricing/limits#app-limits for your current "package":/docs/pricing#packages. - -h2(#40010). 40010: Invalid channel name - -This error occurs when a "channel name":/docs/channels#use does not meet the required format or contains invalid characters. - -h2(#40011). 40011: Stale ring state - -This error occurs when using the channel "enumeration":/docs/api/rest-api#enumeration-rest API and the state of the cluster changes between successive calls, causing a pagination sequence to become invalid. Note: This issue does not occur if the enumeration request is fully satisfied within the first response page. - -h2(#40012). 40012: Invalid @clientId@ - -This error occurs when a @clientId@ is invalid due to disallowed characters or a mismatch between the @clientId@ specified in the request and the one assigned in the authentication "token":/docs/auth/token. - -Examples of this error are when: - -* The client attempts to use @*@ as a @clientId@, which is not allowed because @*@ is used as a "wildcard":/docs/auth/capabilities#wildcards in capability expressions. -* A client tries to assume an ID of @foo@ for an operation, but the token they are using specifies an ID of @bar@. - -h2(#40013). 40013: Invalid message data or encoding - -This error occurs when the SDK is unable to encode the "message payload":/docs/messages due to an unsupported data type. - -An example of this error is when a client attempts to publish a payload that includes something that isn't serializable by an Ably SDK. - -*Resolution:* Try marshalling the payload as JSON or MsgPack before publishing. - -h2(#40015). 40015: Invalid deviceId - -This error occurs when the ID property in a "DeviceDetails":/docs/api/rest-sdk/push-admin#device-details object, sent during a push notification registration request, is invalid. The ID must be a string. - -h2(#40016). 40016: Invalid message name - -This error occurs when the @name@ "property":/docs/messages#properties of a message is not a string. The @name@ field is used to categorize messages within channels, and it must always be a string. - -h2(#40017). 40017: Unsupported protocol version or Invalid API version specified - -This error occurs when a request does not specify a protocol version or provides an invalid version in the request parameters of a "Server-Sent Events (SSE)":/docs/protocols/sse request. This error also occurs when a WebSocket connection to Ably specifies an invalid API version in the request parameters. - -*Resolution*: Ensure that the request specifies a valid protocol version. Note: You will not see this error when using an Ably SDK, as SDKs automatically use valid versions. - -h2(#40020). 40020: Partial failure in batch operation requests - -This error occurs when a "batch":/docs/api/rest-api#batch request partially fails, meaning that some operations succeed while others fail. - -This error can occur for the following endpoints: - -* Revoking tokens: "@POST/revokeTokens@":/docs/api/rest-api#revoke-tokens -* Publishing messages: "@POST/messages@":/docs/api/rest-api#batch-publish -* Retrieving presence data: "@GET/presence@":/docs/api/rest-api#batch-presence - -The following example is a batch operation response that includes partial failures. The @error@ field indicates that some requests within the batch were unsuccessful, while the @batchResponse@ contains individual results for each operation: - -```[json] -{ - "error": "new ErrorInfo('Batched response includes errors', 40020, 400)", - "batchResponse": "results" -} -``` - -h2(#40022). 40022: Invalid resource - -This error occurs when the requested resource is invalid or already exists. It is typically returned by requests to the "Control API":/docs/account/control-api. - -Examples of this error include attempting to create a resource that already exists or providing an invalid resource name. - -*Resolution*: The following steps can help resolve this issue: -* Ensure that an app with the requested name does not already exist in your account. If it does, use a different name. -* Verify that the "capabilities":/docs/auth/capabilities#capability-operations listed in the request are valid when creating an API key. - -h2(#40023). 40023: Action requires a newer protocol version - -This error occurs when the requested operation is only available in a newer version of the Ably protocol than the one specified in the request. This can happen if the client is using an older version of the Ably SDK that does not support the requested operation. - -Examples of this error include attempting to use "channel objects":/docs/liveobjects or message annotations, updates and deletes from an Ably SDK that does not support protocol version 2. - -*Resolution*: The following steps can help resolve this issue: -* Upgrade the Ably SDK to a version that supports the requested operation. - -h2(#40030). 40030: Invalid publish request (unspecified) - -This error occurs when a "publish request":/docs/pub-sub#publish is malformed. - -h2(#40032). 40032: Invalid publish request (impermissible extras field) - -This error occurs when a published message contains arbitrary fields in the "@extras@":/docs/api/realtime-sdk/messages#extras payload that are not allowed by the Ably service. The @extras@ field is reserved for specific objects related to Ably. - -*Resolution*: Place any additional data inside the @headers@ field within @extras@. The @headers@ field must be a flat object (@map@ or equivalent) with no nested structures. If using unenveloped Reactor rules, ensure that header names are in @ASCII@, as they will be converted into HTTP, AMQP, or other protocol headers. - -The following example is a valid @extras@ object: - -```[javascript] -const extras = { - headers: { - header1: 'value1', - header2: 'value2' - } -}; -``` - -h2(#40100). 40100: Unauthorized - -This error occurs when an action cannot be performed due to a lack of "authentication":/docs/auth. There will be additional info in the @message@ property about the reason the action could not be performed. - -h2(#40101). 40101: Invalid credentials - -This error occurs when "authentication":/docs/auth credentials are invalid. The specific error message may provide further details about the cause. - -An example of this error is when a signed token request is invalid due to a mismatched cryptographic signature (MAC does not match) or when the @clientId@ specified in the Ably SDK does not match the @clientId@ in the access token. - -*Resolution*: Review your authentication setup and token request implementation. Ensure the following: - -* The cryptographic signature (MAC) is correct - If a signed token request is invalid, Ably will reject it. -* The API key used to generate the token request is accurate - Double-check for missing or extra characters. -* The token request JSON is correctly formatted and unaltered, including: -** @keyName@: Must match the API key used in the request. -** @clientId@: If provided, it must match the one in the client constructor. -** @ttl@: Must be an integer in milliseconds. -** @timestamp@: Must be an integer in milliseconds. -** @capability@: Must be stringified JSON, not raw JSON. -** @nonce@: Must be a randomly generated string value. -** @mac@: Must be correctly generated using the secret key. -* The @clientId@ in the SDK matches the one in the token. If a @clientId@ is provided in the token, it must align with the @clientId@ set in the Ably client options. -* A @clientId@ cannot be changed on an existing connection. Ensure consistency in authentication. -* For JWT authentication, confirm that @clientId@ is correctly set in @x-ably-clientId@. - -h2(#40102). 40102: Incompatible credentials - -This error occurs when "authentication":/docs/auth credentials do not match the existing connection, causing the connection to enter the "failed state":/docs/connect/states. - -Examples of this error include: - -* Attempting to authenticate with an API key from a different app than the one used for the original connection -* Resuming a connection using credentials tied to a different app -* Calling @auth.authorize@ with an API key that differs from the one originally used to establish the connection - -h2(#40103). 40103: Invalid use of Basic auth over non-TLS transport - -This error occurs when an API key is used over a non-TLS (unencrypted) connection, which is not permitted due to security risks. API keys are long-lived credentials, making them more vulnerable if exposed. Unlike short-lived tokens, API keys remain valid indefinitely, meaning a compromised key presents a significant security risk. - -Non-TLS transports can be inspected by network devices routing traffic between the client and Ably. Ably does not allow API key authentication over non-TLS connections. However, Ably supports "basic authentication":/docs/auth/basic over TLS and "token authentication":/docs/auth/token over non-TLS connections. - -*Resolution*: Select the appropriate "authentication mechanism":/docs/auth#selecting-auth for your use case. - -h2(#40104). 40104: Timestamp not current - -This error occurs when a signed token request sent to Ably is too old. Ably enforces timestamp validation to ensure "@TokenRequest@":/docs/auth/token#token-request remain valid for a limited time, reducing the risk of interception and misuse. - -*Resolutions*: The following steps can help resolve this issue: -* Ensure that the authentication servers clock is accurate when generating signed token requests. -* If time synchronization is unreliable, set the @queryTime@ "ClientOptions":/docs/api/rest-sdk/types#client-options object to true when initializing the Ably client. This ensures Ably's server time is used. -* Do not cache signed token requests on the authentication server or client. Each token request must be freshly generated and used immediately. -* If using Next.js 13, prevent caching issues by setting revalidate to 0 or changing the request method from @GET@ to @POST@ using the @authMethod@ "ClientOption":/docs/api/rest-sdk/types#client-options. - -h2(#40105). 40105: Nonce value replayed - -This error occurs when a signed "token request":/docs/api/realtime-sdk/types#token-request has been used more than once. Ably enforces nonce (number used once) checks to ensure that each signed token request is unique, as a security measure. - -Examples of this error include: -* A client sends a signed token request to Ably but does not receive the response due to network issues. If the client automatically retries the HTTP request in a fallback data center, Ably detects the duplicate nonce and rejects it. -* An authentication server caches and reuses signed token requests instead of generating a unique one for each request. -* A misconfigured "@authCallback@":/docs/auth/token#auth-callback function reuses the same token request on every invocation instead of generating a fresh one. -* The @tokenRequest@ is not renewed. A new token request should be requested from your server at this point: - -```[javascript] -var tokenRequest = ""; -var ably = new Ably.Realtime({ - authCallback: function(tokenParams, callback) { - // This is a mistake. The tokenRequest is not renewed. - A new token request should be requested from your server at this point */ - callback(null, tokenRequest); - } -}); -``` - -*Resolution*: The following steps can help resolve this issue: -* Ensure that each token request is unique and never cached by the authentication server or client. -* Always generate a new token request each time authCallback is invoked. -* If retrieving a token request over HTTP, prevent caching by using the Cache-Control header (no-cache, no-store, must-revalidate) or by adding a cache-busting query string parameter, where the number is regenerated for every request, for example, @?rnd=73849275@. -* If network issues are suspected, check logs and debug the token request process to confirm proper request handling. - -h2(#40106). 40106: Unable to obtain credentials from given parameters - -This error occurs when invalid "authentication":/docs/auth options (key or token) are provided to the Ably SDK, preventing successful authentication. - -An example of this error is when no "API key":/docs/auth#api-keys or "token":/docs/auth/token is supplied, or when an authentication request is made using a token to request another token, instead of an API key. - -h2(#40111). 40111: Connection limits exceeded - -This error occurs when the peak "connection limit":/docs/pricing/limits#connection for your account has been exceeded, preventing new connections from being established until existing ones disconnect. - -h2(#40112). 40112: Account blocked (message limits exceeded) - -This error occurs when your account has exceeded the allocated "message limit":/docs/pricing/limits#message based on your "package":/docs/pricing#packages. Once this limit is reached, further message publishing is blocked. - -h2(#40114). 40114: Account-wide peak channel limit exceeded - -This error occurs when your account has exceeded the concurrent "channel limit":/docs/pricing/limits#channel, preventing additional channels from being created. - -Examples of this error are when the application attempts to open more channels than the account allows, causing new channel creation to be blocked. Also, during development, an implementation error or bug causes unintended channel creation, leading to the limit being reached. - -*Resolution*: Detach unused channels to free up space for new ones. - -h2(#40115). 40115: Account restricted (request limit exceeded) - -This error occurs when your account has exceeded the allocated "limits":/docs/pricing/limits based on your "package":/docs/pricing#packages. - -h2(#40125). 40125: Maximum number of rules per application exceeded - -This error occurs when the application has reached the maximum number of "integration rules":/docs/integrations set by the "limits":/docs/pricing/limits#app-limits for your current package. - -h2(#40127). 40127: Maximum number of keys per application exceeded - -This error occurs when the application has reached the maximum number of "API keys":/docs/account/app/api set by the "limits":/docs/pricing/limits#app-limits for your current package. - -h2(#40131). 40131: Key revoked - -This error occurs when the "Ably API key":/docs/auth#api-keys used to initialize the SDK is no longer valid because it has been "revoked":/docs/auth/revocation by an admin of the application. - -*Resolution*: The following steps can help resolve this issue: -* If you are an admin, go to the "API keys tab":/docs/account/app/api in the Ably dashboard to check for valid keys. Use an existing valid key or create a new one with the necessary permissions. -* If you are not an admin, request a new API key from an administrator or obtain a token request generated with a valid key. - -h2(#40133). 40133: Wrong key; cannot revoke tokens with a different key than the one that issued them - -This error occurs when the "Ably API key":/docs/auth#api-keys used to authorize a token "revocation":/docs/auth/revocation request does not match the key that originally issued the token. - -*Resolution*: The following steps can help resolve this issue: -* Ensure that the public API key ID used in the request matches the key that originally issued the token. -* Verify that the @keyname@ in the request path corresponds with the API key used for authentication. - -h2(#40141). 40141: Token revoked - -This error occurs when attempting to authenticate with a "token":/docs/auth/token that has been "revoked":/docs/auth/revocation and is no longer valid. - -*Resolution*: Ensure that you are using a valid, "non-revoked":/docs/auth/revocation. token for authentication. If needed, generate a new token and use it for authorization. - -h2(#40142). 40142: Token expired - -This error occurs when the authentication "token":/docs/auth/token#refresh has expired and is no longer valid for use. - -An example of this error is when a client attempts to authenticate with a token that has exceeded its time-to-live (TTL). - -*Resolution*: The following steps can help resolve this issue: -* Use "@authUrl@":/docs/auth/token#auth-url or "@authCallback@":/docs/auth/token#auth-callback in your client configuration to enable automatic token renewal. -* If @authUrl@ or @authCallback@ is correctly configured, the client SDK will automatically renew the token when needed, so you may see this error temporarily before renewal occurs. - -h2(#40143). 40143: Token unrecognized - -This error occurs when the provided token is not recognized as a valid Ably "token":/docs/auth/token, Ably "JWT":/docs/auth/token#jwt, or a JWT containing a valid Ably token. - -An example of this error is when a JWT is incorrectly formatted or when an Ably token does not follow the expected structure, for example: @.@. Any token that does not adhere to the correct format will not be recognized. - -*Resolution*: Validate the token format before using it for authentication. If creating a "JWT":/docs/auth/token#jwt, use a standard JWT library to ensure correct generation. If using an Ably token, verify that it matches the expected format as returned from the "@requestToken@":/docs/api/token-request-spec#examples endpoint. - -h2(#40144). 40144: Unexpected error decoding JWT; decode exception - -This error occurs when the "JWT":/docs/auth/token#jwt. provided for authentication cannot be validated by Ably due to incorrect formatting, missing claims, or unsupported configurations. - -This error occurs when the "JWT":/docs/auth/token#jwt provided for authentication cannot be validated by Ably. The specific reason for the failure will be available in the reason property of a "@ConnectionStateChange@":/docs/api/realtime-sdk/types#connection-state-change object or in an error response from a REST request. - -Examples of this error include: -* Missing or invalid payload claims, such as iat (issued at) or exp (expiration). -* Using a deprecated or unsupported signing algorithm. -* Providing an empty string for @x-ably-capability@. -* Using an empty string or non-string value for "@x-ably-revocation-key@":/docs/auth/revocation#revocation-key. -* Missing kid (Key ID) when using "JWT authentication with an API key":/docs/api/realtime-sdk/authentication#ably-jwt. - -h2(#40160). 40160: Action not permitted - -This error occurs when the client does not have permission to perform the requested action. - -An example of this error is when a token request includes an empty "capability object":/docs/auth/capabilities#capabilities-token, for example: @({})@, meaning the client has no assigned permissions, or when the requested "resource":/docs/auth/capabilities#wildcards does not match the API key's allowed capabilities. - -*Resolution*: Ensure the "API key":/docs/auth#api-keys supports the required "capabilities":/docs/auth/capabilities#capabilities-key for the requested action. - -h2(#40161). 40161: Access denied to channel: namespace requires identified clients - -This error occurs when a "non-identified client":/docs/auth/identified-clients attempts to access a channel that requires an identified client. Each application's channel namespaces configuration can be found in its application settings. By default, the identified namespace requires a client to be identified. - -h2(#40170). 40170: Error from client token callback - -This error occurs when an authentication attempt using "@authUrl@":/docs/auth/token#auth-url or "@authCallback@":/docs/auth/token#auth-callback fails due to a timeout, network issue, invalid token format, or another authentication error condition. - -Examples of this error include when a @TokenRequest@ callback times out after the default 10-second limit. Also, when he @authUrl@ response is missing a Content-Type header has an unsupported Content-Type. - -*Resolution*: The following steps can help resolve this issue: -* Check for network latency between the client and the authentication server. -* Ensure the authentication server returns a valid Content-Type header and one of the supported content types: -** @application/json@ -** @text/plain@ -** @application/jwt@ -* Additional error details can be found in the @error.message@ field. - -h2(#40171). 40171: No means provided to renew auth token - -This error occurs when no "@authUrl@":/docs/auth/token#auth-url or "@authCallback@":/docs/auth/token#auth-callback is provided in "@clientOptions@":/docs/getting-started/setup#options when initializing the Ably REST or Realtime SDK. - -Tokens have a set expiration time, and once expired, they are no longer valid for communication with Ably. If @authUrl@ or @authCallback@ is configured, the SDK will automatically request a new token before expiration, ensuring uninterrupted operation. - -*Resolution*: Ensure that @authUrl@ or @authCallback@ is set in your client configuration. This allows the SDK to automatically request a new token before the current one expires. - -h2(#40300). 40300: Forbidden - -This error occurs when a requested action is not permitted. It serves as the default response for forbidden actions and can be triggered by various issues. - -The following are example for this error: -* Mismatched SDK versions, occurring if an application uses multiple versions of the Ably SDK, leading to inconsistencies in connections. -* A disabled account, indicating that the app belongs to an account that has been manually disabled by Ably. -* An incorrect URL for a private cluster. - -h2(#40311). 40311: Operation requires TLS connection - -By default, Ably apps require "TLS":/docs/account/app/settings#channel-rule-configuration for connections. This error occurs when a realtime SDK attempts to connect with TLS disabled (tls: false) while using token authentication. - -*Resolution*: The following steps can help resolve this issue: -* Ensure that the @tls@ "@ClientOption@":/docs/api/realtime-sdk?#client-options is set to true when connecting. -* If using "API key":/docs/account/app/api#create authentication, note that this scenario will result in a "@40103@":#40103 error instead. - -h2(#40330). 40330: Unable to activate account due to placement constraint (unspecified) - -This error occurs when an app belonging to a dedicated (private) "cluster":/docs/platform-customization#dedicated-and-isolated-clusters is accessed using an incorrect endpoint. "Enterprise":/docs/pricing/enterprise customers with private clusters receive "custom":/docs/platform-customization#setting-up-a-custom-environment environment endpoints specific to their deployment. - -An example of this error is when an app configured for a private cluster tries to connect via the default global endpoint. - -*Resolution*: Check your custom environment settings for all connecting clients to ensure they point to the correct private cluster endpoints. - -h2(#40331). 40331: Unable to activate account due to placement constraint (incompatible environment) - -This error occurs when an app that belongs to a dedicated (private) "cluster":/docs/platform-customization#dedicated-and-isolated-clusters is accessed using an incorrect URL. This often happens when the correct environment is not specified when initializing a client library. "Enterprise":/docs/pricing/enterprise customers with private clusters receive "custom":/docs/platform-customization#setting-up-a-custom-environment environment endpoints specific to their deployment. - -If a request arrives at an unexpected dedicated cluster or incorrect region, the account in that scope may be disabled, triggering this error. - -An example of this error is when a client intended for a dedicated environment, such as acme, connects to the default global endpoint (@realtime.ably.io@) instead of the correct dedicated cluster endpoint (@acme-realtime.ably.io@). If the expected environment is not configured, requests may be rejected. - -*Resolution*: Verify that all connecting clients are configured with the correct custom environment settings to ensure they are pointing to the intended dedicated cluster. - -h2(#40332). 40332: Unable to activate account due to placement constraint (incompatible site) - -This error occurs when attempting to connect to an app for an account restricted to a specific region. - -An example of this error is when a client attempts to connect to an Ably app restricted to the EU region but does not specify the EU environment in the SDK configuration. - -*Resolution*: The following steps can help resolve this issue: -* Ensure you are configured with the correct environment for your "region-restricted":/https://faqs.ably.com/do-you-have-an-option-to-keep-my-data-in-europe-or-the-united-states account. -* If your account has a regional constraint, you should have been provided with a "custom":/docs/platform-customization#setting-up-a-custom-environment environment to pass to the "@ClientOptions@":/docs/getting-started/setup#options. -* Verify that your connection settings match the region assigned to your account. - -h2(#40400). 40400: Not found - -This error occurs when the requested resource does not exist. This can apply to an Ably app, client, device, connection, API key, or token. The accompanying error message provides more details about the missing resource. - -Examples of this error include: -* Attempting to authenticate using an Ably API key or token, but the specified appId cannot be found. This may happen if: -** The appId is incorrect. -** The appId does not exist in the current environment (especially in a custom deployment). -* Attempting to authenticate with an incorrect API key ID, which may be due to: -* An invalid API key ID. -* The key not being found in the specified environment. -* Incorrect formatting, particularly case sensitivity issues. - -h2(#42910). 42910: Rate limit exceeded; request rejected - -This error occurs when a "limit":/docs/pricing/limits on your account has been reached, preventing further requests until the limit resets. The duration of the limit depends on the type of rate limit: - -* Instantaneous rate limits typically last up to six seconds before allowing message publishing to resume. -* Other limits may apply on an hourly or monthly basis. - -An example of this error is when a client exceeds the maximum allowed message rate on a channel. - -In the following example, the metric @channel.maxRate@ represents the maximum rate of messages allowed to be published on a channel per second. The permitted rate is 5000 messages per second, but the client is attempting to publish 5015 messages per second, triggering the limit. - -```[text] -Rate limit exceeded; request rejected (nonfatal); -metric = channel.maxRate; -interval = 2018-01-05:10:10:3; -permitted rate = 5000; -current rate = 5015; -scope = channel:[YOUR APP ID]:[YOUR CHANNEL] -(status: 429, code: 42910) (code: 42910, http status: 429) -``` - -*Resolution*: Wait for the rate limit period to reset before retrying. Optimize your message publishing to stay within allowed limits. Upgrade your package if higher throughput is required. Review your account limits to determine which restriction has been hit. - -h2(#42911). 42911: Maximum account-wide instantaneous messages rate exceeded - -This error occurs when the number of "messages":/docs/pricing/limits#message sent per second exceeds the limit imposed on an account. To maintain service reliability for all users, Ably enforces usage limits at different levels, including monthly, hourly, and per-second thresholds. - -h2(#42912). 42912: Channel iteration call already in progress - -This error occurs when multiple concurrent "metadata REST requests":/docs/metadata-stats/metadata#rest are made to retrieve a list of active channels. The API is rate-limited, allowing only one in-flight call at a time. Additional concurrent requests will be rejected with this error. - -*Resolution*: The following steps can help resolve this issue: -* Ensure that only one request is in progress at any given time. -* Implement request queuing or backoff strategies to avoid sending concurrent calls. -* If you require enhanced channel "enumeration capabilities":/docs/api/rest-api#enumeration-rest, visit this page to request access to the preview API. - -h2(#42922). 42922: Rate limit exceeded; too many requests - -This error occurs when a client has made too many requests within a 5-minute time window, causing the request to be rejected. The "limit":/docs/pricing/limits#hitting remains in effect for up to 30 seconds but may persist longer if request volume remains above the threshold from the same IP address. - -This rate limit is in place to protect the Ably platform and is not expected during normal use. - -h2(#50001). 50001: Internal channel error - -This error occurs when there is an internal issue on an Ably channel. - -h2(#50002). 50002: Internal connection error - -This error occurs when there is an internal connection issue. - -h2(#50003). 50003: Timeout error - -This error occurs when a "connection":/docs/connect request to Ably times out. - -An example of this error is when a client attempts to publish a message to a channel, but the operation fails to complete within the allowed time. - -Examples of this error include: -* Poor network conditions affecting connectivity. -* Improper usage of the Ably SDKs leading to unexpected delays. -* Temporary Ably server issues impacting response times. - -h2(#50305). 50305: Ably's routing layer was unable to service this request - -This error occurs as a result of a request not being handled due to an internal routing error within the Ably service. - -h2(#61002). 61002: Activation failed: Present clientId is not compatible with existing device registration - -This error occurs when you previously "activated":/docs/push/configure/device#activate-devices a device for push notifications with a specific @clientId@, but then changed the @clientId@ used for authentication. The mismatch causes the error because the push notification setup tracks the @clientId@ and other details to prevent accidental changes between app launches. The @clientId@ is linked to registrations, such as subscribing by @clientId@. - -*Resolution:* If you need to change your client's @clientId@, deactivate and reactivate the device. This process triggers an internal @device.reset()@ call, which clears and resets the old device details. - -h2(#70001). 70001: Reactor operation failed (POST operation failed) - -This error occurs when a Reactor rule fails due to an issue with the configured endpoint. Ably attempts to send a POST request, but the response is unexpected or unsuccessful. - -h2(#70002). 70002: Reactor operation failed (POST operation returned unexpected code) - -This error occurs when Ably sends a webhook to your server, but the server refuses or returns an unexpected response code. While Ably will retry the request multiple times, repeated failures indicate an issue on the server side. - -h2(#72000). 72000: Ingress operation failed - -This error occurs due to an internal error with the ingress worker. It is an unexpected issue that happens when the worker attempts to execute a rule but encounters an error during the process. - -h2(#72002). 72002: Ingress table is unhealthy - -This error occurs when the rule worker is unable to access or retrieve data from either the "outbox":/docs/livesync/postgres#outbox-table or "nodes":/docs/livesync/postgres#nodes-table table in the database as expected. - -An example of this error is misconfigurations in the database setup or inconsistencies between the provided configuration and the actual database schema or table names. - -*Resolution*: The following steps can help resolve this issue: -* Verify the configuration of the outbox and nodes tables in the database to ensure they are correctly set up and match the rule definition. -* Check for database connectivity issues and confirm that the database is accessible. -* Ensure that the schema and table names align with the expected configuration. - -h2(#72004). 72004: Ingress cannot identify channel, no _ablyChannel field - -This error occurs when a "MongoDB Change Stream":https://www.mongodb.com/docs/manual/changeStreams/#change-streams event does not contain the required @_ablyChannel@ field after being processed through the Change Stream pipeline. This field is essential for identifying the channel where the change event message will be published. - -*Resolution*: The following steps can help resolve this issue: -* Ensure that the @_ablyChannel@ field is present at the root level of the change event. -* Avoid nesting it inside other sections, such as @$fullDocument._ablyChannel@. -* The field must be part of the main structure of the change event to allow proper identification. - -h2(#72005). 72005: Ingress invalid pipeline - -This error occurs when the "MongoDB Change Stream":https://www.mongodb.com/docs/manual/changeStreams/#change-streams fails to start due to an invalid pipeline. An example of this error is when the pipeline syntax does not conform to MongoDB's requirements or contains unrecognized operators. - -*Resolution*: The following steps can help resolve this issue: -* Review the pipeline syntax for errors and ensure all operators are valid. -* Adjust the pipeline to match MongoDB's accepted structure and syntax guidelines. - -h2(#72006). 72006: Unable to resume from change stream - -This error occurs when the "MongoDB Change Stream":https://www.mongodb.com/docs/manual/changeStreams/#change-streams cannot be resumed because the resume token document stored in MongoDB is not in the correct format. - -*Resolution*: The following steps can help resolve this issue: -* Verify the format of the stored resume token document in MongoDB. -* Ensure the token meets the expected structure and format required for MongoDB Change Stream resumption. -* Refer to the MongoDB documentation for guidelines on properly storing and using resume tokens. - -h2(#72007). 72007: Unable to store change stream resume token - -This error occurs when the "MongoDB Change Stream":https://www.mongodb.com/docs/manual/changeStreams/#change-streams resume token cannot be stored in the @ably@ collection of the database. - -*Resolution*: The following steps can help resolve this issue: -* Verify that the integration rule and MongoDB connection string are correctly configured. -* Ensure the database user has the necessary read and write permissions for the @ably@ collection. -* Adjust permissions if needed to allow the token to be successfully stored. - -h2(#80000). 80000: Connection failed - -This error occurs when the SDK is having trouble "connecting":/docs/connect/states#connection-states to Ably, likely due to client-side network connectivity issues. Note: The SDK will automatically retry the connection after 30 seconds. - -h2(#80002). 80002: Connection suspended - -This error occurs when the SDK is having trouble "connecting":/docs/connect/states#connection-states to Ably. This is likely due to client-side network connectivity issues, and has failed to establish a connection within 2 minutes. Note: The SDK will automatically retry the connection after 15 seconds. - -h2(#80003). 80003: Generic disconnection error - -This error occurs when the SDK is having trouble "connecting":/docs/connect/states#connection-states to Ably, likely due to client-side network connectivity issues. Note: The SDK will automatically retry the connection after 15 seconds. - -h2(#80008). 80008: Unable to recover connection (connection expired) - -This error occurs when a "connection":/docs/connect/states#connection-states resume attempt fails because the original connection has expired. This typically happens when the "@resume@":/docs/connect/states#resume attempt occurs after the two-minute window has passed. - -If this error occurs, the client establishes a new connection instead of resuming the old one. Any messages sent during the gap will be missed, unless channel persistence is enabled. - -*Resolution*: Ensure that resume attempts occur within the two-minute window to successfully recover a connection. If message loss is a concern, use "history":/docs/api/realtime-sdk/history to retrieve missed messages. - -h2(#80014). 80014: Connection timed out - -This error occurs when a realtime "connection":/docs/connect/states#connection-states times out after waiting for the default 10-second @realtimeRequestTimeout@ in certain Ably SDKs. - -The request will be automatically retried by the SDK. - -*Resolution*: If the client never connects to the "primary or fallback endpoints":https://faqs.ably.com/routing-around-network-and-dns-issues, check any firewall rules that may be blocking access to Ably's "endpoints":https://faqs.ably.com/if-i-need-to-whitelist-ablys-servers-from-a-firewall-which-ports-ips-and/or-domains-should-i-add. - -h2(#80016). 80016: Operation on superseded connection - -This error occurs when a browser "connection":/docs/connect/states#connection-states upgrades from an HTTP (Comet) transport to WebSockets. It is logged by the client library when operations are performed on the older transport. - -*Resolution*: the following steps can help resolve this issue: -* If this error only appears in logs, it is harmless and does not affect your application. No action is needed. -* If you receive this error as a response to a request, contact Ably support with relevant logs and details, and they will investigate the issue. - -h2(#80017). 80017: Connection closed - -This error occurs when a "connection":/docs/connect/states#connection-states has been closed and an operation is attempted on it, such as calling a channel or presence method, for example, @channel.presence.update@ while the connection is still in a closed state. - -*Resolution*: The following steps can help resolve this issue: -* Check the client's connection state before performing operations to ensure the connection is active. -* If the connection is closed, reconnect before making requests to avoid this error. - -h2(#80018). 80018: Invalid connection ID (invalid format) - -This error occurs when an invalid @connectionId@ is supplied. - -*Resolution*: If you are seeing resumes failing in ably-js, this was a known bug in ably-js versions 1.2.30 through 1.2.33. Upgrading to the latest version of ably-js should resolve the issue. - -h2(#80019). 80019: Auth server rejecting request - -This error occurs when the client library fails to obtain a token using the client-supplied "@authUrl@":/docs/auth/token#auth-url or "@authCallback@":/docs/auth/token#auth-callback. It is raised when the request to the authentication server fails due to an error or exception in the callback. - -h2(#80020). 80020: Continuity loss due to maximum subscribe message rate exceeded - -This error occurs when a client exceeds the "outbound":/docs/pricing/limits#connection subscribe message rate on a realtime connection. - -*Resolution*: The subscriber will receive an @UPDATE@ "channel state change":/docs/api/realtime-sdk/channels#channel-state-change event, indicating that continuity is lost. Use the "@resume@":/docs/connect/states#resume flag to determine whether to recover missing messages or handle the failure accordingly. - -h2(#80021). 80021: Max new connections rate exceeded - -This error occurs when the maximum allowed rate of new connections for an account has been "exceeded":/docs/pricing/limits#hitting. - -h2(#80022). 80022: Unable to find connection - -This error can occur when using the Comet transport, where a @send@ or @recv@ request is sent to the system but reaches a different frontend instance than the one hosting the connection. This can happen due to a disruption on a frontend instance. - -*Resolution*: This is a non-fatal error, and no action is required. The transport will automatically drop and be re-initiated without any need for manual intervention. - -h2(#80023). 80023: Unable to resume connection from a different site - -This error occurs when a disconnected client attempts to resume a "connection":/docs/connect from a different site than the original connection. This typically happens when a client tries to "@resume@":/docs/connect/states#resume via a fallback host. - -*Resolution*: Channel message continuity will not be possible in this scenario. Any messages sent while the client was disconnected will need to be retrieved using "history":/docs/storage-history/history. - -h2(#90001). 90001: Channel operation failed (invalid channel state) - -This error occurs when an application attempts to perform an operation on a channel that is in a "state":/docs/channels/states#connection-state that does not permit it. - -An example of this error is when an application tries to "publish":/docs/pub-sub#publish a message or attach to a channel that is in a failed state due to a prior error. As a result, the operation fails because actions cannot be performed on a channel in this state. - -*Resolution*: The following steps can help resolve this issue: -* Ensure the channel is in an appropriate state before performing any operations. -* Use an Ably SDK to listen for channel state changes and handle operations accordingly. -* Implement state change callbacks to trigger the intended operation when the channel is in a valid "state":/docs/channels/states. - -h2(#90004). 90004: Unable to recover channel (message limit exceeded) - -This error occurs when using the rewind feature with a specified time period, and the total number of messages within the selected timeframe exceeds the maximum "limit":/docs/channels/options/rewind#limits that can be retrieved in a single request. - -h2(#90007). 90007: Channel didn't attach within 00:00:10 - -This error occurs when a channel fails to "attach":/docs/channels/states#attach within the default 10-second timeout. It is most commonly encountered by clients with poor internet connections, where the @ACK@ response to an @ATTACH@ request does not return within the expected timeframe. - -Note: In older versions of the ably-java SDK, this error was incorrectly assigned to error code @91200@. - -*Resolution*: Adjust the @realtimeRequestTimeout@ or @channelRetryTimeout@ (depending on the SDK) to a higher value to allow more time for the attachment process. - -h2(#90010). 90010: Maximum number of channels per connection exceeded - -This error occurs when a Realtime client "attaches":/docs/channels/states#attach to more channels than the account allows on a single connection. This happens when channels are attached but never explicitly detached, causing the limit to be reached. - -*Resolution*: Review your channel "limits":/docs/pricing/limits#channel and ensure that channels are explicitly detached when no longer needed. - -h2(#90021). 90021: Max channel creation rate exceeded - -This error occurs when the "maximum":/docs/pricing/limits#channel rate of channel creation has been exceeded, across an account. Until the rate returns below the limit, new channels may not be created immediately. The Ably SDK will automatically retry every 10 seconds until the request succeeds. - -h2(#91000). 91000: Unable to enter presence channel (no clientId) - -This error occurs when a client attempts to "enter":/docs/chat/rooms/presence#set the "presence":/docs/presence-occupancy/presence set of a channel without specifying a @clientId@. - -A client can be identified in several ways: -* If using "token":/docs/auth/token authentication, ensure the token is associated with a @clientId@ by setting the @clientId@ field in @tokenParams@ when creating a token request or requesting a token. -* If using basic authentication or token authentication with a wildcard @clientId@, set the @clientId@ in the client options when initializing the Ably SDK. -* Specify a @clientId@ at the time of entering presence using "@enterClient()@":/docs/api/realtime-sdk/presence#enterclient. - -h2(#91003). 91003: Maximum member limit exceeded - -This error occurs when the "maximum":/docs/pricing/limits#hitting number of clients in the "presence":/docs/presence-occupancy/presence set for a channel has been reached, preventing additional clients from joining. - -h2(#91005). 91005: Presence state is out of sync - -This is a client-side issue that occurs when an up-to-date "presence":/docs/presence-occupancy/presence set cannot be retrieved due to connection issues. It typically happens when calling @presence.get()@ while the channel is in a suspended state, often caused by an interruption in the client's internet connection. - -*Resolution*: The following steps can help resolve this issue: -* Ensure the client has an active connection before calling @presence.get()@. -* If an outdated presence set is acceptable, set @waitForSync@ to @false@ to retrieve the presence data even when out of sync. - -h2(#92000). 92000: Invalid object message - -This error occurs when an object message used to represent "operations":/docs/liveobjects/concepts/operations and "objects":/docs/liveobjects/concepts/objects is malformed or contains invalid data that cannot be processed. - -* If this error occurs when using the REST API, the error response will include additional details about how to correctly construct your request. -* If this error occurs when using a Realtime SDK, it likely indicates a bug in the client. Please raise an issue in the GitHub repository for the SDK you are using with relevant logs and details. - -h2(#92001). 92001: Objects limit exceeded - -This error occurs when the maximum number of "objects":/docs/liveobjects on the channel has exceeded the allowed "limit":/docs/pricing/limits#channel for the account or application. - -*Resolution*: -* Remove any unnecessary objects from the channel to free up space, for example by "removing":/docs/liveobjects/map#remove any references to them. -* "Upgrade":/docs/pricing your package to increase the "limit":/docs/pricing/limits#channel on the allowed number of objects on the channel. - -h2(#92002). 92002: Unable to submit operation on tombstone object - -This error occurs when attempting to perform an "operation":/docs/liveobjects/concepts/operations on a "tombstone":/docs/liveobjects/concepts/objects#tombstones object (an object that has been marked as deleted). - -*Resolution*: -* Retry the operation on an object that is not a tombstone and is "reachable":/docs/liveobjects/concepts/objects#reachability from the "root object":/docs/liveobjects/concepts/objects#root-object . - -h2(#92003). 92003: Unable to fetch object tree with tombstone object as root - -This error occurs when attempting to fetch an "object":/docs/liveobjects/concepts/objects tree where the specified object is a "tombstone":/docs/liveobjects/concepts/objects#tombstones object (an object that has been marked as deleted). - -You may encounter this error when "fetching objects":/docs/liveobjects/rest-api-usage#fetching-objects-get-children via the REST API using the @children@ query parameter, or if using the "compact":/docs/liveobjects/rest-api-usage#fetching-objects-compact endpoint. - -*Resolution*: -* Retry the operation on an object that is not a tombstone and is "reachable":/docs/liveobjects/concepts/objects#reachability from the "root object":/docs/liveobjects/concepts/objects#root-object . - -h2(#92004). 92004: Object not found - -This error occurs when attempting to access an "object":/docs/liveobjects/concepts/objects that does not exist. - -You may encounter this error when using the "REST API":/docs/liveobjects/rest-api-usage or if calling methods on a "LiveMap":/docs/liveobjects/map or "LiveCounter":/docs/liveobjects/map instance that has been deleted. - -*Resolution*: -* Listen for "lifecycle events":/docs/liveobjects/lifecycle on object instances to be notified when an object is deleted. -* Retry the REST API request with a valid "object ID":/docs/liveobjects/rest-api-usage#updating-objects-by-id or "path":/docs/liveobjects/rest-api-usage#updating-objects-by-path that corresponds to an existing object. - -h2(#92005). 92005: No objects found matching operation path - -This error occurs when no objects are found that match the specified "path":/docs/liveobjects/rest-api-usage#updating-objects-by-path when using the REST API. - -*Resolution*: -* Ensure that the @path@ is correctly specified and corresponds to an existing object. - -h2(#92006). 92006: Unable to perform operation without objectId or path - -This error occurs when attempting to perform an operation without providing either an "object ID":/docs/liveobjects/rest-api-usage#updating-objects-by-id or "path":/docs/liveobjects/rest-api-usage#updating-objects-by-path to identify the target object when using the REST API. - -*Resolution*: -* Ensure that the request includes either an @objectId@ or a @path@ parameter to specify the target object for the operation. - -h2(#92007). 92007: Operation not processable on path - -This error occurs when the requested operation cannot be processed for the object located at the specified "path":/docs/liveobjects/rest-api-usage#updating-objects-by-path when using the REST API. - -You may encounter this error when the type of the object located at the specified path does not support the specified operation (e.g. publishing a @COUNTER_INC@ operation on a "LiveMap":/docs/liveobjects/map instance). - -*Resolution*: -* Ensure that the operation is valid for the type of object at the specified path. - -h2(#101000). 101000: Space name missing - -This error occurs when calling "@spaces.get()@":/docs/spaces/space#options without specifying a space name. The name parameter is required to retrieve a space. - -*Resolution*: Ensure that a valid space name is provided when calling @spaces.get()@: - -```[javascript] -const space = await spaces.get('mySpaceName'); -``` - -h2(#101001). 101001: Not entered space - -This error occurs when calling a function that requires the client to be "entered":/docs/spaces/space#enter into a space, but the client has not yet done so. - -*Resolution*: Ensure that @space.enter()@ is called before performing operations that require the client to be inside the space: - -```[javascript] -const space = await spaces.get('mySpace'); -space.enter({ - username: 'Claire Lemons', - avatar: 'https://slides-internal.com/users/clemons.png', -}); -``` - -h2(#101002). 101002: Lock request exists - -This error occurs when an existing "lock request":/docs/spaces/locking#states is still pending or locked. Nested locks are not supported, so a new lock cannot be requested until the previous one is resolved. - -h2(#101003). 101003: Lock is locked - -This error occurs when a lock is already in the "locked state":/docs/spaces/locking#states, and a pending request did not override or release the lock. - -h2(#101004). 101004: Lock invalidated - -This error occurs when a "lock request":/docs/spaces/locking#states invalidates an existing lock that was already in the locked state. diff --git a/content/errors/index.textile b/content/errors/index.textile deleted file mode 100644 index 509ee3329d..0000000000 --- a/content/errors/index.textile +++ /dev/null @@ -1,131 +0,0 @@ ---- -title: Debugging -meta_description: "Debugging in Ably supported apps, including troubleshooting techniques, logging options, and tools for error analysis." -languages: -- javascript ---- - -Errors can occur in various scenarios when using Ably, such as invalid inputs in requests, authentication issues, or connection problems caused by network disruptions. Proper debugging is essential for building a reliable application and troubleshooting. - -You can debug issues in your Ably-supported app using the following: - -* Set up a custom log handler to capture and manage errors in a way that suits your requirements. -* Meta channels allow you to monitor errors that might not otherwise be visible to clients, providing additional insights into issues. -* The "Dev console":https://ably.com/accounts/any/apps/any/console in your Ably dashboard is a quick and easy way to inspect errors and events, especially during development or debugging. - -h2(#format). Error info - -All errors returned by Ably are standardized and use the "@ErrorInfo@":/docs/api/rest-sdk/types#error-info object: - -```[text] -{ - code: 40005, - statusCode: 400, - cause: Authentication, - nonfatal: false, - href: 'https://help.ably.io/error/40005' -} -``` - -The following explains each property of an @ErrorInfo@ object: - -- @code@ := Ably-specific numeric code indicating the error type. -- @statusCode@ := An HTTP status code providing broader context, such as 400 for a bad request. -- @cause@ := A brief description of the issue. -- @nonfatal@ := A boolean indicating whether the error is critical. -- @Href@ := A direct link to Ably's documentation or for quick troubleshooting references. - -h2(#logging). Logging - -Ably SDKs allow you to customize the function that handles logging. This function is usually set in the options when configuring a client, such as the @ClientOptions@ object for Pub/Sub. - -Two separate properties can be set: - -- @logHandler@ := Provides a custom function for each line of log output. -- @logLevel@ := The verbosity of the logging output, from silent to trace. In some SDKs this is numeric, and in others string. - -The following table explains the @logLevel@ setting for the Ably client, which controls how much logging output is shown. Higher levels include more detailed information: - -|_. Level |_. Description | -| @0@ | No logs | -| @1@ | Errors only | -| @2@ | Errors plus connection and channel state changes | -| @3@ | Abbreviated debug output | -| @4@ | Full debug output | - -The following example configures the Ably client to log only error messages using @logLevel:1@ and processes them with the function @logWriteFun()@: - -```[javascript] -const ablyClient = new Ably.Realtime({ - key: {{API_KEY}}, - logHandler: logWriteFunc, - logLevel: 1 // Errors only -}); -``` - -The following example is a log output for an Ably client configured to log messages using @logLevel:1@: - -```[text] -LOG [Level 1]: Ably: ConnectionManager.failQueuedMessages(): failing 1 queued messages, err = [_ErrorInfo: Application Ptz0jg disabled. -(See https://help.ably.io/error/40300 for help.); statusCode=403; code=40300] -``` - -h2(#meta). Metachannels - -Ably provides a set of "metachannels":/docs/metadata-stats/metadata/subscribe#metachannels that expose internal events from the Ably system. These metachannels are be useful for debugging and monitoring, especially when investigating issues not surfaced directly to clients. - - - -There are two metachannels related to "logging:":/docs/metadata-stats/metadata/subscribe#log - -- @[meta]log@ := Publishes errors that aren't visible to clients, except those related to push notifications. -- @[meta]log:push@ := Similar to @[meta]log@, but only publishes errors related to the delivery of push notifications. - -The following example subscribes to the @[meta]log@ channel: - -```[javascript] -const channel = realtime.channels.get('[meta]log'); -channel.subscribe((msg) => { - console.log(msg); -}); -``` - -The following is an example event published to the @[meta]log@ channel as an "@ErrorInfo@":#format object: - -```[json] -{ - code: 40005, - statusCode: 400, - cause: Authentication, - nonfatal: false, - href: 'https://help.ably.io/error/40005' -} -``` - -h2(#console). Dev console - -The "Dev console":https://ably.com/accounts/any/apps/any/console in your Ably dashboard is a quick and easy way to inspect errors. It provides a live stream of all events in your application, which is especially useful during early-stage development or low-traffic periods when events are easier to track: - -* Monitor all live events in your application for detailed insights. -* Test publishing and subscribing to channels to identify and resolve issues with these functions. - - - -h2(#support). Support tickets - -If the provided information does not resolve your issue, contact Ably "support":https://ably.com/support. When contacting, include details such as your app ID, the error code, and any relevant logs to help troubleshoot. - -The following information is essential for effective troubleshooting, include as much of the following information as possible: - -* Provide timestamps in UTC format. -* Include complete SDK logs from the time of the failure. Ensure these logs show activity before and after the timeout, as SDKs retry failed requests by default. -* Specify which endpoints were accessed. Mention if you use custom client options, the environment setting, and the failing SDK operation. -* State the SDK/s you use, including the platform and versions. -* Include any stack traces related to the error. -* Indicate whether the issue occurs consistently or was a one-time event. -* Provide details to confirm whether the issue was related to your network or Ably's availability. For example, note whether other internet operations were succeeding simultaneously. -* Include the @appID@ associated with the request. diff --git a/content/getting-started/quickstart.textile b/content/getting-started/quickstart.textile index 7e25b52577..0463ba9553 100644 --- a/content/getting-started/quickstart.textile +++ b/content/getting-started/quickstart.textile @@ -756,4 +756,4 @@ This guide introduced the basic concepts of Ably and illustrated how easy it is * Read more about "Pub/Sub":/docs/basics. * Find out more about the "SDKs":/docs/sdks. * Try out some "tutorials":/docs/tutorials. -* Provision Ably apps using the "Control API":/docs/account/control-api. +* Provision Ably apps using the "Control API":/docs/platform/account/control-api. diff --git a/content/getting-started/react-hooks.textile b/content/getting-started/react-hooks.textile index 23fdea5bb6..19168266b7 100644 --- a/content/getting-started/react-hooks.textile +++ b/content/getting-started/react-hooks.textile @@ -40,7 +40,7 @@ h2(#authenticate). Authenticate An "API key":/docs/auth#api-keys is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using "basic authentication":/docs/auth/basic, or to generate tokens for untrusted clients using "token authentication":/docs/auth/token. -"Sign up":https://ably.com/sign-up to Ably to create an API key in the "dashboard":https://ably.com/dashboard or use the "Control API":/docs/account/control-api to create an API programmatically. +"Sign up":https://ably.com/sign-up to Ably to create an API key in the "dashboard":https://ably.com/dashboard or use the "Control API":/docs/platform/account/control-api to create an API programmatically. -[Sign up](https://ably.com/sign-up) to Ably to create an API key in the dashboard or use the [Control API](/docs/account/control-api) to create an API key programmatically. +[Sign up](https://ably.com/sign-up) to Ably to create an API key in the dashboard or use the [Control API](/docs/platform/account/control-api) to create an API key programmatically. API keys and tokens have a set of [capabilities](/docs/auth/capabilities) assigned to them that specify which operations, such as subscribe or publish can be performed on which resources. To use the Chat SDK, the API key requires the following capabilities depending on which features are being used: diff --git a/src/pages/docs/liveobjects/quickstart.mdx b/src/pages/docs/liveobjects/quickstart.mdx index 0baa04d68b..ac9f75e66b 100644 --- a/src/pages/docs/liveobjects/quickstart.mdx +++ b/src/pages/docs/liveobjects/quickstart.mdx @@ -26,7 +26,7 @@ An [API key](/docs/auth#api-keys) is required to authenticate with Ably. API key The examples use [basic authentication](/docs/auth/basic) to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead use [token authentication](/docs/auth/token). -[Sign up](https://ably.com/sign-up) for a free account and create your own API key in the [dashboard](https://ably.com/dashboard) or use the [Control API](/docs/account/control-api) to create an API key programmatically. +[Sign up](https://ably.com/sign-up) for a free account and create your own API key in the [dashboard](https://ably.com/dashboard) or use the [Control API](/docs/platform/account/control-api) to create an API key programmatically. API keys and tokens have a set of [capabilities](/docs/auth/capabilities) assigned to them that specify which operations can be performed on which resources. The following capabilities are available for LiveObjects: diff --git a/src/pages/docs/liveobjects/storage.mdx b/src/pages/docs/liveobjects/storage.mdx index 5207a4b19a..4ddeb8b916 100644 --- a/src/pages/docs/liveobjects/storage.mdx +++ b/src/pages/docs/liveobjects/storage.mdx @@ -37,7 +37,7 @@ Operations themselves are not included in the [history](/docs/storage-history/hi ## Object count and size limits -There is a maximum number of objects that can be stored on a [channel](/docs/pricing/limits#channel), which is configured to 100 objects by default. +There is a maximum number of objects that can be stored on a [channel](/docs/platform/pricing/limits#channel), which is configured to 100 objects by default.