Connecting with Consignly's API requires use of either an OAuth 2.0 connection using Code flow or Client Credentials. In order to support the connection to the API, a Custom App provides the required information to support the OAuth Flow that is required.
A connection to the API will request specific permission scopes and is granted an access token upon a user's approval.
To establish a connection to the API, create a Custom App by visiting the App Integrations in the sidebar and choose the Custom Apps item in the list.
This screen will present you with all the existing Custom Apps that have been created for your organisation. To create a new Custom App, choose the Add button.
Describe your app
To create the Custom App, enter the required information.
- Name: A friendly value required to identify your app.
- Description: A brief note that describes the app in your App Directory listing
-
API Authentication Grant Type: One of Authorization Code or Client Credentials
-
OAuth Redirect Uri: Required if Authorization Code is selected.
The return address Consignly will re-route users to after they have authorised your connection to Consignly. This endpoint is used to capture token information received from Consignly.
-
OAuth Redirect Uri: Required if Authorization Code is selected.
Optional details can be entered to help provide more information on the connection to your organisation users.
- About: A brief note about your app
- How does this work?: An explanation about how this app will work with Consignly
- Website Url: A website address that users can navigate to in order to find further information about the app
A new Custom App screen in Consignly
Principle and user inheritance
Every access token is issued with a Principal, which is the effective user identity used for authorization in Consignly.
The Edit Principal option on the Custom App Detail
Client Credentials
When a custom app is created, Consignly creates a dedicated Principal User for that integration.
This Principal User is initially created with permissions similar to the user who created the Custom App. API calls made with Client Credentials run as this Principal User.
Authorization Code
The Principal is the user who signs in and approves the app during consent. API calls run as that approving user and are limited by that user's permissions.
Because Client Credentials uses a dedicated Principal User, the integration can continue working even if the user who created the Custom App is later deactivated.
If the integration should have less access, use Edit Principal on the Custom App to reduce the Principal User's permissions.
Consignment Permissions on the Edit Principal view