Hello there, and welcome to Stream's REST API documentation!
The REST documentation is recommended for advanced users that want to write their own API clients.
Have a look below at the official clients, framework integrations, and community-contributed libraries.
Both authentication methods create a signature that is specific to the requested resource (feed, or application).
When dealing with authentication tokens, you should keep in mind that tokens are passwords.
Never share tokens with untrusted parties.
Requests to the Stream API specific to a single feed use Feed Authentication to authenticate requests.
JSON Web Tokens (JWT)
This authentication method uses JSON Web Tokens (JWT) to authenticate requests.
This is a standardized method to give permissions by signing a JSON formatted token with a secret key.
Read more about JWT at jwt.io/introduction.
The great news is that libraries are available in many languages for encoding and decoding JSON Web Tokens.
Have a look at the jwt.io libraries page to see if your language of choice is supported.
And yes, a Delphi library is available.
JWT usage for feed authentication
For feed authentication the client should send a token that is signed
with the secret of the app.
This token must include a permission scope compatible to the request
that is being performed.
Permission scopes are defined using the following fields:
resource, action and feed_id.
The resource field of the JWT payload allows you to define which API endpoints can be accessed, you can pick one of the following:
The action field of the JWT payload allows you to define which HTTP verbs are allowed by a request:
The feed_id field in the JWT payload specifies for which
feed the permissions specified before are granted.
The value of this field should be a concatenation of the feed
group's slug and the user_id of the feed
instance (eg."news1234). Similarly to the resource and
action field a single * character will grant
the permissions on all feeds.
Sending an authenticated request
Once the token is generated correctly it still needs to be used to
authenticate a request. This is done by seting two HTTP headers on the
Important: Some of the JWT libraries prefix the
generated token with the string "Bearer". This prefix should be removed
before sending the request.
Below are some example tokens for different use cases:
// A token which allows every possible action on all feeds. Useful for
// development and server side, but unsuitable for usage on the client.
// A token which allows reading, modification and deletion of activities on
// the feed of the user with id 123.
// A token which allows reading the followers of the feed of user with id 123.
When you are performing actions that are not specific to a single feed (such as application configuration, or batching),
Application Authentication is used.
The Feed Detail endpoint allows you to delete activities.
The Stream API allows you to delete activities by their activity id or foreign id:
The activity id is returned to you in the response when the activity is first created.
The foreign id is a unique reference which represents the activity in your database.
Note: By setting foreign ids you ensure uniqueness and no longer need to store the response-based activity id in your database.
Read more about foreign ids versus activity ids over at the Stream general docs.
Note: Deleting by foreign id requires setting a foreign_id URL query parameter to "1":
Send a value of 1 to indicate you want to delete by foreign id