After you have created a Custom App, you can set about establishing a connection to it.
If you have specified a Connect Url in your Custom App, then adding your app via the App Directory will present a button that will allow you to connect to Consignly via the Connect Url you have specified.
If a Connect Url has not been specified, then the app can connect to your organisation directly using Consignly's API and providing the Client Id and Secret and requesting the appropriate scopes.
This will trigger an OAuth flow that will require a Consignly user to login and authorise the app to connect to Consignly.
The app will connect to Consignly using the scopes requested, but is ultimately limited by the permissions of the user that authorised the app in Consignly.
After the app has connected to your organisation, it will appear as a connection in your connected Apps list.
Establish an OAuth connection by sending a user to authorise your connection
To get started, your app should direct users to the following URL
https://identity.consignlyhq.com/connect/authorize
The following values should be passed in as parameters:
- response_type=code
- client_id issued by the Custom App on creation
- scope permissions to request (see below)
- redirect_uri the URL on your server to redirect the client back to (this must match the Redirect Uri configured on the Custom App)
- state a unique string to be passed back on completion (optional - see below)
Scopes
The scope parameter is a space-separated list of OAuth scopes, indicating what data you would like your connection to be able to access. Scopes are used in conjunction with user permissions, so even if you request full access scopes, the connection won't be able to complete tasks that the user doesn't have permission to do.
The complete list of scopes is available here.
State
The state parameter should be used to avoid forgery attacks. Pass in a value that is unique to the connection / user you are sending through for authorisation. It will be passed back after the user completes authorisation.
Users are redirected back to you
Once the user successfully authorises your app, Consignly will redirect the user back to your specified redirect_uri. The redirect will contain the following information passed through:
- code a temporary code that may only be exchanged once. It expires 1 minute after issuance.
- state (if supplied). If the states don't match, the request may have been created by a different client and you should abort the connection process
Exchange the code for a token
Now that you have received the code and verified the state, you may exchange the code for an Access Token. If you have requested the offline_access scope then you will also receive a Refresh Token.
To do this, create a POST to the token endpoint below:
https://identity.consignlyhq.com/connect/token
The request will require an authorization header containing your Custom App's ClientId and Secret base64 encoded into a basic authorization header:
- Authorization: "Basic " + base64encode(client_id + ":" + client_secret)
The request body will need to contain the grant type, code, and redirect_uri:
- grant_type=authorization_code
- code=The authorisation code you received in the redirect
- redirect_uri=The same Redirect Uri that was used when requesting the code
Receive the tokens
The token endpoint will verify all the parameters entered by you in the request, making sure that the ClientId and Secret match, the code hasn't expired, and the Redirect Uri is legitimate.
If everything verifies successfully, you tokens will be generated and returned in the response, as follows:
- access_token The token used to call the Consignly API
- expires_in The amount of seconds until the access token expires
- token_type: Bearer
- refresh_token The token used to refresh the access token once it has expired. This is only returned if the offline_access scope is requested.
Token Expiry
All the tokens provided have an associated expiry time. Access tokens and refresh tokens can be exchanged prior to expiry.
- Code: 1 minutes
- Access Token: 60 minutes
- Refresh Token: 90 days
Access Token
The Access Token is a JWT which can be decoded to a JSON object.
One important feature of the Access Token is the consignly_org_id. This defines the organisation that your access token is authorised for and needs to be used on all API calls to Consigly.
Use the Consignly API
You can make requests against the Consignly API by adding the following headers into your request:
- Authorization: "Bearer " + access_token
- x-consignly-org-id: consignly_org_id from the access token
Refreshing Access and Refresh Tokens
Access tokens expire after 60 minutes. Your app can refresh an Access Token by using a Refresh Token. This requires no user-interaction to support this.
Get a refresh token by requesting the offline_access scope during the initial OAuth connection. Refresh tokens expire after 90 days.
To refresh your Access Token you need to POST to the token endpoint:
https://identity.consignlyhq.com/connect/token
The request will require an authorization header containing your Custom App's ClientId and Secret base64 encoded into a basic authorization header:
- Authorization: "Basic " + base64encode(client_id + ":" + client_secret)
The request body will need to contain the grant type, code, and redirect_uri:
- grant_type=refresh_token
- refresh_token=Your refresh token
The response will contain a new Access Token and Refresh Token. You must persist both tokens in order to maintain API access.
Revoking tokens
You can revoke a user's Refresh Token and remove all their connections to your app by making a request to the revocation endpoint.
To revoke a refresh token, you need to POST to the revocation endpoint:
https://identity.consignlyhq.com/connect/revocation
The request will require an authorization header containing your Custom App's ClientId and Secret base64 encoded into a basic authorization header:
- Authorization: "Basic " + base64encode(client_id + ":" + client_secret)
The request body will need to contain the grant type, code, and redirect_uri:
- token=Your refresh token
A successful request will return a 200 response with an empty response body.