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

One of:
object-1 object object-2 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.

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
    Hide response attributes Show response attributes object
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"
}