Access to Link APIs requires authentication using either OAuth or a Personal Access Token (PAT). Both methods operate on behalf of a Link user, whose roles and permissions determine which API operations are available.
This document describes the supported authentication methods and how to use them in your integrations. We recommend using a dedicated service account with permissions limited to those required by the integration.
OAuth
Supported OAuth flow
For API integrations, Link supports the Resource Owner Password Credentials (ROPC) flow. The client obtains an access token by sending a Link user's username and password, together with the registered client's credentials, to the token endpoint.
A dedicated service user is recommended. The user must have the role(s) required by the API being accessed.
Refresh tokens may be used to obtain new access tokens where issued.
Link does not currently support the Authorization Code flow or the Client Credentials grant for API integrations. Registering a client with a client ID and secret identifies the application; it does not mean that the Client Credentials grant is supported.
Personal Access Token (PAT)
As an alternative to OAuth, a user can authenticate with a Personal Access Token (PAT).
These tokens can be used to gain access to different Link API’s (like the existing OAuth2 authentication):
-
Inbox/Outbox
-
Rest
-
Generic Http Handler
A personal access token is created directly to a user-account in Link - and therefor it will give access to whatever permissions that are linked to that user.
Typically specific service-accounts will be created for this API purpose - and the service-accounts should not be able to log into the Link UI.
How to use the PAT
The use of the PAT is more simple than the Oauth2 flow. The Link API’s will expect the token to be provided via the Basic Authentication scheme (https://en.wikipedia.org/wiki/Basic_access_authentication )
The username of the Basic Authentication header must be empty - and the PAT must be provided as the password (the same way Microsoft gives access to their Azure Devops API: https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows - see the “Use a PAT” section).