API Tokens
  • 2 Minutes to read
  • Dark
  • PDF

API Tokens

  • Dark
  • PDF

Rivery offers the functionality to interact with Rivery resources (e.g. Rivers) using the Rivery API.

For interactive technical documentation of all Rivery API endpoints available, see here.


The API uses a bearer token as an authentication method.

Admin users on an account can create, view, and delete tokens for the account.
This functionality is limited to admin users only.

Working with tokens

On the left side panel under admin click on API Tokens 

A list will appear showing all of the API tokens under your account with details on the tokens, including the token name, created time, created by and more.



Creating a token

To create a token click on the Add Token button at the upper left corner of the screen.

A new window will appear where you will need to enter the token name and choose the scopes (permissions) you would grant to the token.

The token name must be unique and it is recommended you choose informative names for your tokens.

Each scope in the list can be added or removed by clicking the checkbox button next to the scope name. Each scope has a description informing what access the scope grants to the token.


Once you are satisfied with the token definitions click on the create button. if you wish to stop the process at this point click cancel.

After you've clicked on the create button a new window will appear showing the generated token.


**Do note that this is the only time you will be able to see the token so make sure to copy your new token using the copy button and save it somewhere private.**

Click on done to exit the screen, you have now successfully created your token.

The new token will be added to your token list and you can view the scopes granted to the token by clicking on the View button in the token list.


Deleting a token

To delete a token click on the trash icon for that token in the right side of the View token screen.

A pop up will appear where you will need to confirm you would like to delete the token.

Once a token is deleted it can never be used again.


Making API calls

The token must be used as a bearer token under Authorization in the header.
Let's look at a real example of how to execute a river.

First, you will need to find the river id.

This can be done by navigating to a specific river in the console and extracting the river id from the URL.

The river id is the last identifier in the URL:

In this case, the river id is: 5e773

Let's assume your token is: XYZ

This would be the specific curl in our example:

curl -X POST "https://console.rivery.io/api/run" 
-H "accept: application/json"
-H "Authorization: Bearer XYZ"
-H "Content-Type: application/json"
-d "{ \"river_id\": \"5e773\"}"

The general curl is the following:

curl -X POST "https://console.rivery.io/api/run" 
-H "accept: application/json"
-H "Authorization: Bearer {token}"
-H "Content-Type: application/json"
-d "{ \"river_id\": \"{river_id}\"}"


Technical use cases

If you are using editors like Python, make sure to JSON dumps the data payload inside the POST call. I.e., you can use the following use case to run a river:

import requests
import json
RIVER_ID = '1234567abcd'
url = 'https://console.rivery.io/api.run'
payload = json.dumps({"river_id": RIVER_ID})  # converting dictionary into JSON string
headers = {'accept': 'application/json', 'Authorization': f"Bearer {river_api_token}", 'Content-Type': 'application/json'}
r = requests.post(url, data=payload, headers=headers)

API rate limits and limitations

  • You can have up to 20 tokens active in your account.
  • Each token has a rate limit of 100 calls per minute.

Rate limits and token limitations can change without prior notice and will reflect on this page.


Was this article helpful?

What's Next