Request an access token

POST /keys/{keyName}/requestToken

This is the means by which clients obtain access tokens to use the service. You can see how to construct an Ably TokenRequest in the Ably TokenRequest spec documentation, although we recommend you use an Ably SDK rather to create a TokenRequest, as the construction of a TokenRequest is complex. The resulting token response object contains the token properties as defined in Ably TokenRequest spec. Authentication is not required if using a Signed TokenRequest.

Path parameters

keyName string Required

The key name comprises of the app ID and key ID of an API key.

Body object

keyName string Required

Name of the key used for the TokenRequest. The keyName comprises of the app ID and key ID on an API Key.
capability object Required

The capabilities (i.e. a set of channel names/namespaces and, for each, a set of operations) which should be a subset of the set of capabilities associated with the key specified in keyName.
clientId string

The client ID to be assosciated with the token. Can be set to * to allow for any client ID to be used.
timestamp integer Required

Time of creation of the Ably TokenRequest.
nonce string Required

An unquoted, un-escaped random string of at least 16 characters. Used to ensure the Ably TokenRequest cannot be reused.

keyName string Required

Name of the key used for the TokenRequest. The keyName comprises of the app ID and key ID on an API Key.
capability object Required

The capabilities (i.e. a set of channel names/namespaces and, for each, a set of operations) which should be a subset of the set of capabilities associated with the key specified in keyName.
clientId string

The client ID to be assosciated with the token. Can be set to * to allow for any client ID to be used.
timestamp integer Required

Time of creation of the Ably TokenRequest.
nonce string Required

An unquoted, un-escaped random string of at least 16 characters. Used to ensure the Ably TokenRequest cannot be reused.
mac string Required

A signature, generated as an HMAC of each of the above components, using the key secret value.

Responses

2XX

OK
Hide response attributes Show response attributes object
- token string
  
  The Ably Token.
- keyName string
  
  Name of the key used to create the token
- issued integer
  
  Timestamp of token creation.
- expires integer
  
  Timestamp of token expiration.
- capability string
  
  Regular expression representation of the capabilities of the token.
default

Error
Hide headers attributes Show headers attributes
- x-ably-errorcode integer
  
  The error code.
- x-ably-errormessage string
  
  The error message.
- x-ably-serverid string Required
  
  The ID for the server communicated with.
Hide response attributes Show response attributes object
- message string
  
  Message explaining the error's cause.
- code integer
  
  Error code.
- statusCode integer
  
  Status error code.
- href string
  
  Link to help with error.
- serverId string
  
  Server ID with which error was encountered.

POST /keys/{keyName}/requestToken

curl \
 -X POST https://rest.ably.io/keys/{keyName}/requestToken \
 -H "Content-Type: application/json" \
 -d '{"keyName":"YourKey.Name","timestamp":"1559124196551","capability":{"channel1":["publish","subscribe"],"wildcard:channels:*":["publish"]}}'

Request example

{
  "keyName": "YourKey.Name",
  "timestamp": "1559124196551",
  "capability": {
    "channel1": [
      "publish",
      "subscribe"
    ],
    "wildcard:channels:*": [
      "publish"
    ]
  }
}

Request examples

{
  "keyName": "xVLyHw.LMJZxw",
  "capability": {
    "channel1": [
      "publish",
      "subscribe"
    ]
  },
  "clientId": "string",
  "timestamp": 42,
  "nonce": "string"
}

{
  "keyName": "xVLyHw.LMJZxw",
  "capability": {
    "channel1": [
      "publish",
      "subscribe"
    ]
  },
  "clientId": "string",
  "timestamp": 42,
  "nonce": "string",
  "mac": "string"
}

Response examples (2XX)

{
  "token": "string",
  "keyName": "string",
  "issued": 42,
  "expires": 42,
  "capability": "string"
}

Response examples (2XX)

{
  "token": "string",
  "keyName": "string",
  "issued": 42,
  "expires": 42,
  "capability": "string"
}

Response examples (default)

# Headers
x-ably-errorcode: 42
x-ably-errormessage: string
x-ably-serverid: string

# Payload
{
  "message": "string",
  "code": 42,
  "statusCode": 42,
  "href": "string",
  "serverId": "string"
}

Response examples (default)

# Headers
x-ably-errorcode: 42
x-ably-errormessage: string
x-ably-serverid: string

# Payload
{
  "message": "string",
  "code": 42,
  "statusCode": 42,
  "href": "string",
  "serverId": "string"
}