Credentials
Retrieve your authorization credentials to access the API
Before you can access our API, you will need at least two pieces of identifying information: your bearer token, and your Workspace (Organization) ID. For some APIs, you may also need your unique User ID. All of these can be accessed through the authorization endpoint, as described below.
Before you can use the endpoint, you will need some software that can use APIs, such as cURL or Python.
Authorization endpoint
The API endpoint for authorization is https://cite.petal.org/api/auth. You will need to send a POST request to the endpoint, with the following parameters:
The email you use to sign in on Petal
Your password
The sample code below shows how to make this request. Remember to replace your_email@example.com and your_password with your actual login credentials.
If successful, this request should return a JSON object with all the information you need. In particular, you are looking for these fields:
A cryptic bearer token that identifies you. It will be needed for all other API access.
Your unique User ID.
A list of the unique IDs of all Workspaces (also called Organizations) of which you are part.
Since every Petal user can create or join a number of Workspaces (also called Organizations in our API), you will need to find the ID of the particular Workspace you wish to work with, if you are in more than one Workspace. You might be able to do this by examining your role in each Workspace in the parameter
A list of your roles in all your Workspaces. Follows the same order as the organization_ids parameter.
However, if it’s still not clear which Workspace ID you need, you can follow the instructions in the next section to identify the correct Workspace.
Specifying your Workspace (Organization) ID
To do this, you should make a GET request to the https://cite.petal.org/api/user/<id>/organization/list endpoint. You will need to provide the bearer token you have just obtained from the previous step, as well as your user ID. Replace the sample values with your own in the code example below to get started.
If successful, this request should return a list of all Organizations (Workspaces) you are part of. It will provide the name and description for each Organization in the list. The is_personal field indicates whether the Organization is a personal one (created automatically upon user account creation). Using a combination of these fields, you should be able to identify the Organization you wish to work with.
Once you have noted down the unique ID (in the id field), you are all set to begin to use our API for the correct Workspace.