What is an app API key

Every application has one or more API keys assigned to it needed for authentication with the Real-time or REST end points.

 

An API key string may look like this: "I2E_JQ.OqUdfg:EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0".  The API key is made up of three parts:

  • I2E_JQ is the public app ID (the part before the first period)
  • OqUdfg is the public app key ID (the part after the period and before the colon)
  • I2E_JQ.OqUdfg is the public API key ID (both the public app ID and app key ID together)
  • EVKVTCBlzLBPYJiCZTsIW_pqylJ9WVRB5K9P19Ap1y0 is the API key secret and should never be shared to untrusted parties (the part after the colon)

 

Each API key set up in the app dashboard is comprised of:

 

  • The API key string that is your private secret and should never be made public.  This API key string is used in all of our client libraries and for authentication with the REST API.
  • A set of privileges that the API key has including:
    • Publish - can publish messages to channels
    • Subscribe - can subscribe to messages on channels
    • History - can retrieve message and presence state history on channels
    • Presence - can register presence and subscribe to presence events on a channel
    • Statistics - can retrieve usage statistics for the app
  • Channel restrictions can be configured for an API key to limit the channels it has access to.  By default an API key will have access to all channels, however if channel restrictions such as "general,public:*" then users of this API key will have access to the "general" channel and all channels within the "public" namespace.  Find out more about channel namespaces.
 
Note: API keys can be used to not only authenticate with Ably but also to issue Ably Tokens or sign Ably TokenRequests and Ably JWTs (JSON Web Tokens).  Any tokens will only ever have a subset of the permissions privileges and channel restrictions for the API key i.e. an issued token will never have more privileges than the API key used to issue it.  Find out more about Ably authentication.

 

Step by step instructions for setting up and managing API keys.