---
title: "Request an access token"
method: POST
path: "/keys/{keyName}/requestToken"
tags: ["Authentication"]
---

# 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](https://www.ably.io/documentation/rest-api/token-request-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

## Request body

- union
  - TokenRequest
    - `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](https://www.ably.io/documentation/core-features/authentication#capabilities-explained) (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](https://www.ably.io/documentation/core-features/authentication#identified-clients) 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.
  - SignedTokenRequest
    - `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](https://www.ably.io/documentation/core-features/authentication#capabilities-explained) (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](https://www.ably.io/documentation/core-features/authentication#identified-clients) 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.

## Response `2XX`

OK

- TokenDetails
  - `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.

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/ably/apis/platform-api.md) · [All operations](https://skmtc.dev/ably/apis/platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ably/platform-api/revisions/d9cf7e90bb58/schema)