PerspioTalk API endpoints use oAuth for authentication. oAuth is an open protocol, and we currently use OAuth2. This means you'll be working with both Access Tokens and Refresh Tokens.

An access token (access_token) is required to interact with any PerspioTalk endpoint, and generating an access token should be your first step when working with PerspioTalk APIs. To generate an access_token, one of the two authorisation flows (grant types) must be followed: Authorization Code Flow and Client Credentials Flow.

The decision on which flow to use will depend on the level of integration you plan to implement between your system and Perspio.

Flow	Access Scope	Client Credentials	Interactive Login	Refresh Token
Client Credentials Flow	READ ONLY	YES	NO	NO
Authorization Code Flow	READ/WRITE	NO	YES	YES

Generally, the Client Credentials Flow is an excellent place to start to allow you to quickly and easily read data from Perspio. Once comfortable with basic GET operations, you can move to the Authorization Code Flow for more advanced bi-directional integrations.

Once you have identified which flow is best for your integration, please follow the below steps.

Client Credentials Flow

READ-ONLY ACCESS

This flow is limited to read-only operations and is a good choice if you want to acquire data from Perspio. This flow is much easier to start with as it does not require an interactive login. Most GET operations are accessible using this access_token generated from this flow.

Step 1: Create Application
Step 2: Get Access Token
Step 3: Use Access Token

❗️
No Refresh Tokens (Client Credentials Flow)
Refresh tokens are not generated when using the Client Credentials Flow. When your access token expires or becomes invalid, request a new access_toekn from the token endpoint with your client_id + client_secret.

Authorization Code Flow

READ/WRITE ACCESS

This flow provides access to read and write operations and will be required if your integration needs to POST any data to Perspio. This flow requires one additional step to the Client Credentials Flow, first generating an Authorisation Code (code) from an interactive login process. This flow can access allread and writes operations available within PesrpioTalk.

The access token can be refreshed using refresh tokens.

Step 1: Create Application
Step 2: Create User
Step 3: Get Access Token
Step 4: Use Access Token
Step 5: Refresh Token

Additional details - Authorization Code Flow

🚧
Refresh Tokens (Authorization Code Flow Only)
Access tokens are intended to have limited lifetimes, so a process must be in place for generating a new one in case of a token expirt. (Tokens could also be revoked or lack sufficient privileges which will also require generating a new one)
Step 5: Refresh Token explains how to generate a new access token with the refresh_token provided in the same response that contains the access_token.