You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/pages/docs/chat/api/javascript/auth.mdx
+16-16Lines changed: 16 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@ title: Authentication
3
3
meta_description: ""
4
4
---
5
5
6
-
The [ChatClient](/docs/chat/api/javascript/chat-client) requires a realtime client generated by the core [Pub/Sub SDK](LINK) to establish a connection with Ably. This realtime client is used to handle authentication with Ably.
6
+
The [ChatClient](/docs/chat/api/javascript/chat-client) requires a realtime client generated by the core [Pub/Sub SDK](/docs/basics) to establish a connection with Ably. This realtime client is used to handle authentication with Ably.
7
7
8
8
There are broadly three mechanisms of authentication with Ably:
9
9
@@ -27,7 +27,7 @@ Use the following parameters:
27
27
28
28
| Parameter | Description | Type |
29
29
| --------- | ----------- | ---- |
30
-
|`clientOptions`| The options to pass to customize the client connection. |[`ClientOptions`](#clientoptions)|
30
+
|`clientOptions`| The options to pass to customize the client connection. |[`ClientOptions`](#ClientOptions)|
31
31
32
32
### ClientOptions
33
33
@@ -66,7 +66,7 @@ Instructs the SDK to fetch a new Ably Token or JWT.
66
66
67
67
It upgrades the current realtime connection to use the new token if the client is already connected. If they haven't yet connected then it initiates a connection to Ably.
68
68
69
-
Any [`TokenParams`](#tokenparams) and [`AuthOptions`](#authoptions) will be used as the new defaults for subsequent implicit and explicit token requests. They also entirely replace, as opposed to merging with, the current stored values.
69
+
Any [`TokenParams`](#TokenParams) and [`AuthOptions`](#AuthOptions) will be used as the new defaults for subsequent implicit and explicit token requests. They also entirely replace, as opposed to merging with, the current stored values.
|`tokenParams`|*Optional* The parameters of the token for the request. |[`TokenParams`](#tokenparams)|
80
-
|`authOptions`|*Optional* The authentication options for the request. |[`AuthOptions`](#authoptions)|
79
+
|`tokenParams`|*Optional* The parameters of the token for the request. |[`TokenParams`](#TokenParams)|
80
+
|`authOptions`|*Optional* The authentication options for the request. |[`AuthOptions`](#AuthOptions)|
81
81
82
82
#### TokenParams
83
83
@@ -106,7 +106,7 @@ It has the following properties:
106
106
|`authMethod`|*Optional* The HTTP method to use for `authUrl` requests. Either `GET` or `POST`. The default is `GET`. | String |
107
107
|`authHeaders`|*Optional* A set of key-value pair headers to add to `authUrl` requests. | Object |
108
108
|`authParams`|*Optional* A set of key-value pairs to add to `authUrl` requests. When the `authMethod` is `GET` params are added to the URL. When the `authMethod` is `POST` they are sent as URL-encoded form data. | Object |
109
-
|`tokenDetails`|*Optional* An authenticated `TokenDetails` object. This is commonly used in testing. In production it is preferable to use a method that renews the token automatically since they are short-lived. |[`TokenDetails`](#tokendetails)|
109
+
|`tokenDetails`|*Optional* An authenticated `TokenDetails` object. This is commonly used in testing. In production it is preferable to use a method that renews the token automatically since they are short-lived. |[`TokenDetails`](#TokenDetails)|
110
110
|`key`|*Optional* A full API key string. Used for basic authentication requests. | String |
111
111
|`token`|*Optional* An authenticated token. Either a `TokenDetails` object, a token string from the `token` property of a `TokenDetails` component of a `TokenRequest` response, or a JWT. This is commonly used in testing. In production it is preferable to use a method that renews the token automatically since they are short-lived. | String \| Object |
112
112
|`queryTime`|*Optional* If `true`, queries Ably for the current time when issuing `TokenRequests`. The default is `false`. | Boolean |
@@ -128,7 +128,7 @@ It has the following properties:
128
128
129
129
#### TokenRequest
130
130
131
-
Contains the properties of a request for a token to Ably. Tokens are generated using [`requestToken()`](#requesttoken).
131
+
Contains the properties of a request for a token to Ably. Tokens are generated using [`requestToken()`](#RequestToken).
132
132
133
133
It has the following properties:
134
134
@@ -144,15 +144,15 @@ It has the following properties:
144
144
145
145
### Returns
146
146
147
-
Returns a promise. On success, the promise is fulfilled with the new [`TokenDetails`](#tokendetails) once the connection has been upgraded or initiated. On failure, the connection will move to the `SUSPENDED` or `FAILED` state, and the promise will be rejected with an [`ErrorInfo`](/docs/chat/api/javascript/error-info) object which explains the error.
147
+
Returns a promise. On success, the promise is fulfilled with the new [`TokenDetails`](#TokenDetails) once the connection has been upgraded or initiated. On failure, the connection will move to the `SUSPENDED` or `FAILED` state, and the promise will be rejected with an [`ErrorInfo`](/docs/chat/api/javascript/error-info) object which explains the error.
148
148
149
149
---
150
150
151
151
## Create a tokenRequest <aid="createTokenRequest"/>
152
152
153
153
`auth.createTokenRequest()`
154
154
155
-
Creates and signs an Ably [`TokenRequest`](#tokenrequest) based on the specified [`TokenParams`](#tokenparams) and [`AuthOptions`](#authoptions). If no `TokenParams` or `AuthOptions` are specified it will use those already stored by the SDK, set in the [`ClientOptions`](#clientoptions) when the SDK was instantiated or updated via an [`authorize()`](#authorize) request. New values replace the existing ones rather than merging with them.
155
+
Creates and signs an Ably [`TokenRequest`](#TokenRequest) based on the specified [`TokenParams`](#TokenParams) and [`AuthOptions`](#AuthOptions). If no `TokenParams` or `AuthOptions` are specified it will use those already stored by the SDK, set in the [`ClientOptions`](#ClientOptions) when the SDK was instantiated or updated via an [`authorize()`](#Authorize) request. New values replace the existing ones rather than merging with them.
@@ -162,20 +162,20 @@ Use the following parameters:
162
162
163
163
| Parameter | Description | Type |
164
164
| --------- | ----------- | ---- |
165
-
|`tokenParams`|*Optional* The parameters of the token for the request. |[`TokenParams`](#tokenparams)|
166
-
|`authOptions`|*Optional* The authentication options for the request. |[`AuthOptions`](#authoptions)|
165
+
|`tokenParams`|*Optional* The parameters of the token for the request. |[`TokenParams`](#TokenParams)|
166
+
|`authOptions`|*Optional* The authentication options for the request. |[`AuthOptions`](#AuthOptions)|
167
167
168
168
### Returns
169
169
170
-
Returns a promise. On success it will be fulfilled with a [`TokenRequest`](#tokenrequest) object. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/chat/api/javascript/error-info) object which explains the error.
170
+
Returns a promise. On success it will be fulfilled with a [`TokenRequest`](#TokenRequest) object. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/chat/api/javascript/error-info) object which explains the error.
171
171
172
172
---
173
173
174
174
## Request a token <aid="requesttoken"/>
175
175
176
176
`auth.requestToken()`
177
177
178
-
Calls the `requestToken` endpoint to obtain an Ably Token according to the specified [`TokenParams`](#tokenparams) and [`AuthOptions`](#authoptions). If no `TokenParams` or `AuthOptions` are specified it will use those already stored by the SDK, set in the [`ClientOptions`](#clientoptions) when the SDK was instantiated or updated via an [`authorize()`](#authorize) request. New values replace the existing ones rather than merging with them.
178
+
Calls the `requestToken` endpoint to obtain an Ably Token according to the specified [`TokenParams`](#TokenParams) and [`AuthOptions`](#AuthOptions). If no `TokenParams` or `AuthOptions` are specified it will use those already stored by the SDK, set in the [`ClientOptions`](#ClientOptions) when the SDK was instantiated or updated via an [`authorize()`](#Authorize) request. New values replace the existing ones rather than merging with them.
|`tokenParams`|*Optional* The parameters of the token for the request. |[`TokenParams`](#tokenparams)|
189
-
|`authOptions`|*Optional* The authentication options for the request. |[`AuthOptions`](#authoptions)|
188
+
|`tokenParams`|*Optional* The parameters of the token for the request. |[`TokenParams`](#TokenParams)|
189
+
|`authOptions`|*Optional* The authentication options for the request. |[`AuthOptions`](#AuthOptions)|
190
190
191
191
### Returns
192
192
193
-
Returns a promise. On success it will be fulfilled with a [`TokenDetails`](#tokendetails) object. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/chat/api/javascript/error-info) object which explains the error.
193
+
Returns a promise. On success it will be fulfilled with a [`TokenDetails`](#TokenDetails) object. Upon failure, the promise will be rejected with an [`ErrorInfo`](/docs/chat/api/javascript/error-info) object which explains the error.
Copy file name to clipboardExpand all lines: src/pages/docs/chat/api/javascript/chat-client.mdx
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,9 +12,9 @@ The `ChatClient` class is the core client for Ably Chat.
12
12
| Property | Description | Type |
13
13
| -------- | ----------- | ---- |
14
14
|`clientId`| The clientId of the current client. | String |
15
-
|`clientOptions`| The resolved client options for the client, including any defaults that have been set. |[`ChatClientOptions`](#chatclientoptions)|
15
+
|`clientOptions`| The resolved client options for the client, including any defaults that have been set. |[`ChatClientOptions`](#ChatClientOptions)|
16
16
|`connection`| The underlying connection to Ably, which can be used to monitor the client's connection to Ably servers. |[`Connection`](/docs/chat/api/javascript/connection)|
17
-
|`realtime`| The underlying Ably Realtime client. |[`Realtime`](#realtime)|
17
+
|`realtime`| The underlying Ably Realtime client. |[`Realtime`](#Realtime)|
18
18
|`rooms`| The rooms object, which provides access to chat rooms. |[`Rooms`](/docs/chat/api/javascript/rooms)|
19
19
20
20
---
@@ -33,17 +33,17 @@ Use the following parameters:
33
33
34
34
| Parameter | Description | Type |
35
35
| --------- | ----------- | ---- |
36
-
|`realtime`| The Ably Realtime client. |[`Realtime`](https://sdk.ably.com/builds/ably/ably-js/main/typedoc/)|
37
-
|`clientOptions`|*Optional* The client options. |[`ChatClientOptions`](#chatclientoptions)|
36
+
|`realtime`| The Ably Realtime client. |[`Realtime`](#Realtime)|
37
+
|`clientOptions`|*Optional* The client options. |[`ChatClientOptions`](#ChatClientOptions)|
38
38
39
39
#### ChatClientOptions
40
40
41
41
The following `ChatClientOptions` can be set:
42
42
43
43
| Properties | Description | Type |
44
44
| ---------- | ----------- | ---- |
45
-
|`logLevel`|*Optional* The logging level to use. The default is `LogLevel.Error`. |[`LogLevel`](#loglevel)|
46
-
|`logHandler`|*Optional* A custom log handler. The default behavior will log messages to the console. |[`LogHandler`](#loghandler)|
45
+
|`logLevel`|*Optional* The logging level to use. The default is `LogLevel.Error`. |[`LogLevel`](#LogLevel)|
46
+
|`logHandler`|*Optional* A custom log handler. The default behavior will log messages to the console. |[`LogHandler`](#LogHandler)|
47
47
48
48
#### LogLevel
49
49
@@ -73,8 +73,8 @@ Use the following parameters:
73
73
| Parameter | Description | Type |
74
74
| --------- | ----------- | ---- |
75
75
|`message`| The message being logged. | String |
76
-
|`logLevel`| The log level of the message. |[`LogLevel`](#loglevel)|
77
-
|`context`|*Optional* The context of the log message as key-value pairs. |[`LogContext`](#logcontext)|
76
+
|`logLevel`| The log level of the message. |[`LogLevel`](#LogLevel)|
77
+
|`context`|*Optional* The context of the log message as key-value pairs. |[`LogContext`](#LogContext)|
78
78
79
79
#### LogContext
80
80
@@ -102,7 +102,7 @@ const chatClient = new ChatClient(realtimeClient, {
102
102
103
103
## Realtime
104
104
105
-
The Chat constructor requires a realtime client generated using the core [Pub/Sub SDK]() to establish a connection with Ably. The realtime client handles [authentication](/docs/chat/api/javascript/auth) with Ably.
105
+
The Chat constructor requires a realtime client generated using the core [Pub/Sub SDK](/docs/basics) to establish a connection with Ably. The realtime client handles [authentication](/docs/chat/api/javascript/auth) with Ably.
106
106
107
107
`new Ably.Realtime(ClientOptions clientOptions)`
108
108
@@ -112,7 +112,7 @@ Use the following parameters:
112
112
113
113
| Parameter | Description | Type |
114
114
| --------- | ----------- | ---- |
115
-
|`clientOptions`| The options to pass to customize the client connection. |[`ClientOptions`](#clientoptions)|
115
+
|`clientOptions`| The options to pass to customize the client connection. |[`ClientOptions`](#ClientOptions)|
Copy file name to clipboardExpand all lines: src/pages/docs/chat/api/javascript/connection.mdx
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -14,7 +14,7 @@ Access it via `chatClient.connection`.
14
14
| Property | Description | Type |
15
15
| -------- | ----------- | ---- |
16
16
|`error`| The current error, if any, that caused the connection to enter the current status. |[`ErrorInfo`](/docs/chat/api/javascript/error-info)\|`undefined`|
17
-
|`status`| The current status of the connection. |[`ConnectionStatus`](#connectionstatus)|
17
+
|`status`| The current status of the connection. |[`ConnectionStatus`](#ConnectionStatus)|
18
18
19
19
---
20
20
@@ -47,7 +47,7 @@ Use the following parameters:
47
47
48
48
| Parameter | Description | Type |
49
49
| --------- | ----------- | ---- |
50
-
|`listener`| The function to call when the status changes. |[`ConnectionStatusListener`](#connectionstatuslistener)|
50
+
|`listener`| The function to call when the status changes. |[`ConnectionStatusListener`](#ConnectionStatusListener)|
51
51
52
52
#### ConnectionStatusListener
53
53
@@ -59,7 +59,7 @@ It uses the following parameters:
59
59
60
60
| Parameter | Description | Type |
61
61
| --------- | ----------- | ---- |
62
-
|`change`| The change in connection status. |[`ConnectionStatusChange`](#connectionstatuschange)|
62
+
|`change`| The change in connection status. |[`ConnectionStatusChange`](#ConnectionStatusChange)|
63
63
64
64
#### ConnectionStatusChange
65
65
@@ -69,14 +69,14 @@ It has the following properties:
69
69
70
70
| Property | Description | Type |
71
71
| -------- | ----------- | ---- |
72
-
|`previous`| The previous connection status. |[`ConnectionStatus`](#connectionstatus)|
73
-
|`current`| The current connection status. |[`ConnectionStatus`](#connectionstatus)|
72
+
|`previous`| The previous connection status. |[`ConnectionStatus`](#ConnectionStatus)|
73
+
|`current`| The current connection status. |[`ConnectionStatus`](#ConnectionStatus)|
74
74
|`reason`|*Optional* The error that caused the change, if any. |[`ErrorInfo`](/docs/chat/api/javascript/error-info)|
75
75
|`timestamp`| The time at which the status change occurred. | Date |
76
76
77
77
### Returns
78
78
79
-
Returns a [`StatusSubscription`](/docs/chat/api/javascript/subscriptions#statussubscription) object that can be used to unregister the listener.
79
+
Returns a [`StatusSubscription`](/docs/chat/api/javascript/subscriptions#StatusSubscription) object that can be used to unregister the listener.
0 commit comments