There are 4 separate APIs that can be used to interact with your Jostle Instance:

Activity
Tasks
Discussions
Provisioning

And each section requires a unique token. Tokens are obtained within the Jostle UI and are linked to a specific user within a specific Jostle instance. If your org is just starting with Jostle API integrations, please see the section at the bottom on enabling.

📝 Tasks

The Tasks API provides for the capability to create Tasks, update Tasks, add comments & attachments to Tasks, and to obtain the current status of a Task. Only Tasks visible to the user associated with the provided token will be accessible via the API, in other words, the user associated with the token must be either the Task assignee or a collaborator on the Task.

Assignees and collaborators must be specified either by username or user id. The /people endpoint (use Tasks token) can be used to obtain a list of users in the instance, providing usernames, ids, and the display name (first & last name).

You can obtain tokens in the Tasks view:

Your user needs to be given Tasks API access by a system administrator, before this control will be available.

📝 Discussions

The Discussions API can be used to add messages to a discussion, and to retrieve the content of a Discussion. Access is limited to Discussions for which the user associated with the token is a moderator. The List function can be used to obtain a list (name and id) of Discussions for which the token has moderator rights.

Tokens for Discussions can be obtained from within the Discussions view.

Your user needs to be given Discussions API access by a system administrator, before this control will be available.

📝 Activity

The Activity API allows posting messages to the Activity stream. Tokens must be associated with an Automation user in the instance, so setup may require an automation user to be created and activated first. Once API access has been enabled and there is at least one automation user in the instance, then any News Editor can create a token for use with the Activity API.

📝 Provisioning

The providing API can be used add, delete and suspend users, plus manage all of the user profile data. This API follows the SCIM standard https://scim.cloud/ so is compatible with many identity management tools such as Okta and Azure Tenure.

The provisioning API requires an automation user in the Jostle instance which will be attached to the token that is used for this API. If you do not yet have an automation user, or wish to create one dedicated to provisioning then proceed to the manage automation user page in the admin section (note: remember to activated the user):

Next proceed to the Manage Provisioning page (if unavailable reach out to [email protected] to request having the feature enabled) in the Administration section.

This page will allow you to create a provisioning token and give it a useful description. Remember it is good practise to issue separate tokens for different tools and use cases, so it is possible to quickly revoke a token while fully understanding what will be disabled.

Enabling APIs

Before any API use can happen, a system administrator needs to review and accept the applicable terms. This can be done in the Manage API rights page in the Administration section.

Once APIs have been enabled for the organization, then in the case of the Tasks and Discussions API, individual users can be given access to one or both APIs.

Only users defined in these lists will be able to access the token issuing controls in the main UI.

Adding the token to your call

The token should be contained in an Authorization header, like "Authorization" : "Bearer " + Token,
e.g. "Authorization": "Bearer 10000663-ea53c4ba-ce2e-43f7-9172-3b00d953acc3"