Personal Access Tokens (or PATs for short) provide a way to authorise actions on the API that are long lived and are appropriate for use with third-party applications. You can also assign a role to a PAT to limit its scope.
What are long-lived tokens?
When you sign in via the API, you receive a token but it has a very short lifespan of 60 minutes - this means, 60 minutes after its creation, it becomes invalid.
PATs have a longer lifetime. They don't expire after creation but can be revoked when required.
Be aware that you'll need a JWT gotten from a successful (2FA authorised) login action to authorise the call when creating a PAT (or a previously created PAT).
What is a Role?
A role is a logical grouping of permissions — which define what an entity can do, or has access to. When creating a PAT, you can assign it a role, which will grant it all permissions that are available to that role.
Irrespective of the selected role (or assigned permissions a PAT has), they will always be applied based on the context of the permissions the user creating the PAT has.
For instance, if a Payable Admin tries to assign the owner role to a PAT they’re creating, the permissions not belonging to payable admin will be stripped off.
Summary
A PAT either has all the permissions of the user creating it, or a subset — never more.
Using a PAT
When you issue a new PAT using the Create PAT endpoint or on your dashboard, the actual token is only ever displayed once - it's the value of the token key in the response and looks something like 1|pat-ZuKpi3vjhgvLyy2ATp0Gyp0NPyPGXTPhpxpaMwnv.
Make sure to store the "token"
If you don't store the value of the "token" key from the create call, you'll not be able to get or see the value ever again - this is made this way for security reasons.
Also, issuing & revoking tokens is quite trivial so it's not too big a problem.
To use the token, you only need to supply the stored token in your Authorization header like so:
Authorization: Bearer TOKEN_VALUE
For example:
Authorization: Bearer 1|pat-ZuKpi3vjhgvLyy2ATp0Gyp0NPyPGXTPhpxpaMwnv