Ably Authentication API

openapi: 3.2.0
info:
  title: Platform Authentication API
  description: The REST API specification for Ably.
  version: 1.1.1
  contact:
    name: Ably Support
    url: https://www.ably.io/contact
    email: support@ably.io
servers:
- url: https://rest.ably.io
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Authentication
paths:
  /keys/{keyName}/requestToken:
    parameters:
    - $ref: '#/components/parameters/versionHeader'
    - $ref: '#/components/parameters/responseFormat'
    post:
      summary: Request an access token
      operationId: requestAccessToken
      description: 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.
      tags:
      - Authentication
      parameters:
      - $ref: '#/components/parameters/key_name'
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/TokenRequest'
              - $ref: '#/components/schemas/SignedTokenRequest'
            example:
              keyName: YourKey.Name
              timestamp: '1559124196551'
              capability:
                channel1:
                - publish
                - subscribe
                wildcard:channels:*:
                - publish
      responses:
        2XX:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenDetails'
            application/x-msgpack:
              schema:
                $ref: '#/components/schemas/TokenDetails'
        default:
          $ref: '#/components/responses/Error'
components:
  headers:
    ErrorCode:
      description: The error code.
      schema:
        type: integer
    ErrorMessage:
      description: The error message.
      schema:
        type: string
    ServerId:
      description: The ID for the server communicated with.
      schema:
        type: string
      required: true
  schemas:
    Error:
      type: object
      description: Returned error from failed REST.
      properties:
        message:
          type: string
          description: Message explaining the error's cause.
        code:
          type: integer
          description: Error code.
        statusCode:
          type: integer
          description: Status error code.
        href:
          type: string
          description: Link to help with error.
        serverId:
          type: string
          description: Server ID with which error was encountered.
    TokenRequest:
      type: object
      properties:
        keyName:
          type: string
          description: Name of the key used for the TokenRequest. The keyName comprises of the app ID and key ID on an API Key.
          example: xVLyHw.LMJZxw
        capability:
          type: object
          description: 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.
          example:
            channel1:
            - publish
            - subscribe
        clientId:
          type: string
          description: 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:
          type: integer
          description: Time of creation of the Ably TokenRequest.
        nonce:
          type: string
          description: An unquoted, un-escaped random string of at least 16 characters. Used to ensure the Ably TokenRequest cannot be reused.
      required:
      - keyName
      - capability
      - timestamp
      - nonce
    SignedTokenRequest:
      allOf:
      - $ref: '#/components/schemas/TokenRequest'
      - type: object
        properties:
          mac:
            type: string
            description: A signature, generated as an HMAC of each of the above components, using the key secret value.
        required:
        - mac
    TokenDetails:
      type: object
      properties:
        token:
          type: string
          description: The Ably Token.
        keyName:
          type: string
          description: Name of the key used to create the token
        issued:
          type: integer
          description: Timestamp of token creation.
        expires:
          type: integer
          description: Timestamp of token expiration.
        capability:
          type: string
          description: Regular expression representation of the capabilities of the token.
  responses:
    Error:
      description: Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/x-msgpack:
          schema:
            $ref: '#/components/schemas/Error'
        text/html:
          schema:
            $ref: '#/components/schemas/Error'
      headers:
        x-ably-errorcode:
          $ref: '#/components/headers/ErrorCode'
        x-ably-errormessage:
          $ref: '#/components/headers/ErrorMessage'
        x-ably-serverid:
          $ref: '#/components/headers/ServerId'
  parameters:
    responseFormat:
      in: query
      name: format
      schema:
        type: string
        enum:
        - json
        - jsonp
        - msgpack
        - html
      description: The response format you would like
    versionHeader:
      in: header
      name: X-Ably-Version
      schema:
        type: string
      description: The version of the API you wish to use.
    key_name:
      name: keyName
      in: path
      schema:
        type: string
      required: true
      description: The [key name](https://www.ably.io/documentation/rest-api/token-request-spec#api-key-format) comprises of the app ID and key ID of an API key.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic Authentication using an [API key](https://www.ably.io/documentation/core-features/authentication#basic-authentication).
    bearerAuth:
      type: http
      scheme: bearer
      description: Token Authentication using an [Ably Token](https://www.ably.io/documentation/core-features/authentication#basic-authentication), or optionally an [Ably JWT](https://www.ably.io/documentation/core-features/authentication#ably-jwt-process).
x-provenance:
  method: harvested
  publisher: Ably
  source: https://raw.githubusercontent.com/ably/open-specs/main/definitions/platform-v1.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)