Private Feeds

Some interactions with the Feeds API require authorization to perform. Authorization comes in the form of an access token signed with your service key that only your servers have access to, so that we can be sure that you authorized the request.

Overview

This page gives a high level overview of how the authorization system works. If you want a tutorial on how to use it, check out the final part of the comment wall tutorial which explains how to restrict read access with private feeds, or for lower level details see Authorization.

All requests to the Feeds API that come directly from your server will be made with an appropriate access token which the server SDK generates for you. The client will need access to restrictced resources too though, so needs some way of fetching a token from your server -- since the client does not (and should not!) have access to your service key.

Reading Private Feeds

A feed is private if its ID begins private-, e.g. private-foo,private-secret-stuff, and private-go-away; otherwise it is public, e.g.foo, not-so-secret, hey-listen. Public feeds don't require any authorization to read, so if you want to publish sensitive or secret information to a feed, you should use a private feed.

If you ask the client SDK to subscribe to a private feed it will first send a request to your server to fetch an access token, then make the subscription request to Feeds API along with this token.

1
2
3
4
5
6
7
8
9
Your Server                 Client                 Feeds API
     |                        |                        |
     |   POST /feeds/tokens   |                        |
     | <--------------------- |                        |
     |                        |                        |
     |      access_token      |   SUBSCRIBE feed_id    |
     | ---------------------> | ---------------------> |
     |                        |    + acccess_token     |
     |                        |                        |

Each token gives access to a single feed and tokens are cached in the client until they expire (after 24 hours). If the client already has a token granting access to the feed in question then the communication with your server will be skipped, and the request will just be made straight to Feeds API.

Setup an Auth Endpoint

You'll need to configure an endpoint on your server that accepts POST requests from clients asking for tokens, and responds either with an appropriate token or with an error.

For example, on an Express server:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
app.post("/feeds/tokens", (req, res) => {
  const hasPermission = (action, feedId) => {
    // Check that action === "READ" and check req.session
    // or similar to confirm that the currently logged in
    // user should have access to feedId.
    //
    // Return true or false, or a Promise that resolves to
    // true or false.
  };
  feeds.authorizeFeed(req, hasPermission)
    .then(data => res.send(data))
    .catch(err => {
      res.status(400).send(`${err.name}: ${err.message}`)
    });
});

authorizeFeed extracts the action and feedId from the request, and defers to hasPermission to decide whether to resolve with an access token for that action and feed, or reject. For now your hasPermission callback should always reject requests for actions other than "READ".

By default the client SDK attempts to retrieve tokens from /feeds/tokens. If you set up your endpoint on some other path, say /my/custom/auth/path, then you have to tell the client where to look by setting the authEndpoint option in the Feeds constructor.

1
2
3
4
const feeds = Feeds({
  instanceLocator,
  authEndpoint: "/my/custom/auth/path",
});

Other than this, there is nothing you need to do on the client -- it'll fetch tokens automatically as and when it needs them.

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.