The client ID this client is identified as when publishing messages or entering presence.
The value is resolved from the clientId in ClientOptions, or from the clientId in the token the client authenticated with. A conflict between the two raises an ErrorInfo.
The value is unset for an anonymous client, for example a key-authenticated client with no clientId configured. A populated value makes this an identified client. Guard against an unset value despite the declared type.
Instructs the library to get a new token immediately.
On a realtime client it re-authenticates a connection that is already in the connected state, and otherwise starts or restarts the connection. The returned promise resolves only once the new token has taken effect on a connection in the connected state. It rejects with an ErrorInfo if re-authentication fails or the connection cannot be established.
The client must have a way to obtain a token, so the resolved AuthOptions must include one of the token authentication mechanisms authCallback, authUrl, or key, or a token supplied directly. Without any of these the call rejects with an ErrorInfo.
authorize() cannot change the API key, so passing an authOptions.key that differs from the one the client was constructed with is rejected with an ErrorInfo.
Any TokenParams and AuthOptions passed in are stored as the new defaults for subsequent token requests. They replace, rather than merge with, the stored defaults.
Optional tokenParams: TokenParams
A TokenParams object.
Optional authOptions: AuthOptions
An AuthOptions object.
A promise which, upon success, will be fulfilled with a TokenDetails object. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
const tokenDetails = await realtime.auth.authorize({ clientId: 'bob' });
https://ably.com/docs/pub-sub/api/javascript/realtime/auth#authorize
A TokenParams object.
An AuthOptions object.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use realtime.auth.authorize(tokenParams) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
realtime.auth.authorize(tokenParams, authOptions, (err, token) => {});
// v2:
const token = await realtime.auth.authorize(tokenParams, authOptions);
Creates and signs an Ably TokenRequest based on the specified TokenParams and AuthOptions. Use this to implement an Ably Token request callback for use by other clients.
An API key value must be available locally to sign the request, supplied either in the client's ClientOptions or as key in the authOptions argument. Without a key the call rejects with an ErrorInfo, since a client using token authentication cannot construct token requests itself and must instead obtain the TokenRequest from the key owner.
Both TokenParams and AuthOptions are optional. When omitted or null, the client's stored defaults are used, as specified at instantiation or later updated by an authorize() request. Any values passed in replace, rather than merge with, those defaults.
Optional tokenParams: TokenParams
A TokenParams object.
Optional authOptions: AuthOptions
An AuthOptions object.
A promise which, upon success, will be fulfilled with a TokenRequest object. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
const tokenRequest = await realtime.auth.createTokenRequest({ clientId: 'bob' });
https://ably.com/docs/pub-sub/api/javascript/realtime/auth#create-token-request
A TokenParams object.
An AuthOptions object.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use realtime.auth.createTokenRequest(tokenParams) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
realtime.auth.createTokenRequest(tokenParams, authOptions, (err, req) => {});
// v2:
const req = await realtime.auth.createTokenRequest(tokenParams, authOptions);
Obtains an Ably Token according to the specified TokenParams and AuthOptions.
Both TokenParams and AuthOptions are optional. When omitted or null, the client's stored defaults are used, as specified at instantiation or later updated by an authorize() request. Any values passed in replace, rather than merge with, those defaults.
The client must have a way to obtain a token, so the resolved AuthOptions must include one of the token authentication mechanisms authCallback, authUrl, or key. A client given only a literal token cannot request a new one and the call rejects with an ErrorInfo.
Optional TokenParams: TokenParams
A TokenParams object.
Optional authOptions: AuthOptions
An AuthOptions object.
A promise which, upon success, will be fulfilled with a TokenDetails object. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
const tokenDetails = await realtime.auth.requestToken({ clientId: 'bob' });
https://ably.com/docs/pub-sub/api/javascript/realtime/auth#request-token
A TokenParams object.
An AuthOptions object.
v1 Node-style callback (no longer supported).
v1 callback signature — no longer supported. Use realtime.auth.requestToken(tokenParams) and await the returned promise. See the v2 migration guide.
// v1 (no longer supported — IDE shows this with strikethrough):
realtime.auth.requestToken(tokenParams, authOptions, (err, token) => {});
// v2:
const token = await realtime.auth.requestToken(tokenParams, authOptions);
Revokes the tokens specified by the provided array of TokenRevocationTargetSpecifiers.
The client making this call must be authenticated with an API key (basic auth), not a token. A token-authenticated client cannot revoke tokens and the call rejects with an ErrorInfo.
Only tokens issued by an API key that had revocable tokens enabled before the token was issued can be revoked.
An array of TokenRevocationTargetSpecifier objects.
Optional options: TokenRevocationOptions
A set of options which are used to modify the revocation request.
A promise which, upon success, will be fulfilled with a BatchResult containing information about the result of the token revocation request for each provided [TokenRevocationTargetSpecifier]TokenRevocationTargetSpecifier. Upon failure, the promise will be rejected with an ErrorInfo object which explains the error.
const result = await rest.auth.revokeTokens([{ type: 'clientId', value: 'bob' }]);
https://ably.com/docs/pub-sub/api/javascript/realtime/auth#revoke-tokens
Generated using TypeDoc
Creates Ably TokenRequest objects and obtains Ably Tokens from Ably to subsequently issue to less trusted clients.