Ably Docs

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

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"
}