Authorization

Access to resources in the feeds API are controlled by granting permission to perform an action on a path. An action is either a READ, a WRITE or aDELETE. A path is the part of the URL after the instance ID.

Overview

Available actions on a path include a READ, a WRITE or aDELETE -- where READ corresponds to the HTTP methods GET and SUBSCRIBE,WRITE corresponds to the HTTP method POST, and DELETE corresponds to the HTTP method DELETE. A path is the part of the URL after the instance ID -- for example, to POST to the following URL

1
https://us1.pusherplatform.io/services/feeds/v1/:instance_id/feeds/:feed_id/items

one would need WRITE access to the path feeds/:feed_id/items.

Requests to read a public feed (a feed with ID that doesn't begin"private-") need not be authorized -- for every other request to the Feeds API, an Authorization header must be provided. This header contains a JWT signed with a secret that only the server has access to.

To use Feeds via existing SDKs it is unnecessary to know the details below; for a higher level overview of how to set up authorization for reading private feeds on the client, see Private feeds.

Token Schema

The token claims should conform to the following JSON schema:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "$schema": "http://json-schema.org/schema#",
  "type": "object",
  "properties": {
    "app": { "type": "string", "pattern": "^[a-zA-Z0-9_-]{1,50}$" },
    "iss": { "type": "string", "pattern": "^api_keys/" },
    "iat": { "type": "integer" },
    "exp": { "type": "integer" },
    "feeds": {
      "type": "object",
      "properties": {
        "permission": {
          "type": "object",
          "properties": {
            "path": { "type": "string" },
            "action": {
              "type": "string",
              "enum": [ "READ", "WRITE", "DELETE", "*" ]
            }
          },
          "required": [ "path", "action" ]
        }
      },
      "required": [ "permission" ]
    },
    "sub": { "type": "string" }
  },
  "required": [ "app", "iss", "iat", "exp", "feeds" ]
}
  • app: Your instance ID (the last part of the instance locator)
  • iss: An identifier for the key used to sign the token, has the format"api_keys/<key_id>"
  • iat: The unix timestamp that the token was issued at (seconds)
  • exp: The unix timestamp that the token expires at -- should be 24 hours later than iat
  • feeds: An object with the following key
    • permission: An object with the following keys
    • path: The path that the token grants the holder access to; either the path of a resource, or "*"
    • action: The action that the token grants the holder to perform; one of"READ", "WRITE", "DELETE", or "*"
  • sub: [Optional] A user ID.

Tokens with path or action set to "*" grant access to all paths or actions -- these tokens should be limited to use on the server.

Secret Key

The key (available on your dashboard) has the format key_id:key_secret. The key_secret is used to sign the token, and thekey_id is provided in the iss claim so that we can verify the signature.

For example, given a key this-is-the-id:this-is-the-secret, we would sign the following payload with this-is-the-secret:

1
2
3
4
5
6
7
8
9
10
11
12
{
  "app": "4ff02853-helo-4590-81c7-42c09f25d113",
  "iss": "api_keys/this-is-the-id",
  "iat": 1506355405,
  "exp": 1506441805,
  "feeds": {
    "permission": {
      "path": "*",
      "action": "*"
    }
  }
}

The resulting string is sent in an Authorization header in the following format

1
Authorization: Bearer <signed_token>

Fetching a Token

The secret key should be kept on the server, so when the client needs to access a restricted resource, it must first fetch a token from the server. To do this, the client should send a POST request to some pre-arranged endpoint , along with a urlencoded body containing action, path, and grant_type.grant_type is always client_credentials. action and path are as described above.

1
action=READ&path=feeds%2Fprivate-callum%2Fitems&grant_type=client_credentials

The expected response is either 403 Forbidden or 200 with body

1
2
3
4
5
{
  "access_token": "<signed_token>",
  "token_type": "bearer",
  "expires_in": 86400
}

The client should cache tokens and keep track of expires_in to know when a fresh one is needed.

Server Token

For convenience, the server may make all of its own requests with a token granting access to path and action both "*".

Did you find this document useful?

We are always striving to create the most accurate and informative docs as possible. If there is something especially wrong (or right) here then please let us know.