Personal Access Tokens

Introduction to Personal Access Tokens

tip

For more information about which authentication method to use, see Authentication.

Universal GUI

Personal Access Tokens are a secure way for users to allow external parties to connect with their application. They can create their own tokens and assign a limited set of application permissions to them.

Or, from a technical point of view: they are a way for external parties to log in to the Indicium API with a token instead of basic authentication. This token can be scoped to only access the necessary resources within the rights of the user. User credentials are not shared.

If a PAT is leaked, the token can be revoked by the user or an IAM administrator without the need to change the user's password. And if a user needs to change their password for whatever reason, the PAT will keep working

Examples

With a PAT, users can achieve features in an application without waiting for others to implement them.

Examples for applications:

• Set up various webhooks (for example, with a service like If This Then That (IFTTT)) that performs actions on the user's behalf or polls the user's data in a Thinkwise application, such as:

  • Synchronizing appointments between a Thinkwise application and their personal Google or Apple calendar
  • Synchronizing data between a Thinkwise application and another application, such as a Finance or CRM application, on behalf of the user
  • Setting up an automated process to receive an email or text message when the status of a task, order, invoice, transaction, project, or ticket changes
  • Starting a long-running process flow at night, such as importing data or generating invoices on behalf of the user
  • Setting up an AI Assistant to answer questions about the data in a Thinkwise application

Examples for Indicium administration (see also Endpoints):

• Integrating Indicium health checks into load balancer decision making
• Verifying Indicium and database health after running a CI/CD pipeline

Examples where a PAT token could be used instead of a Client Application with grant type Client credentials:

• The third-party application does not support OAuth
• You want to configure a specific end date for the integration
• You want to use a single IAM user for multiple integrations with slightly differing permission sets
• You want to use a single IAM user for multiple identical integrations but have the freedom to change permission sets for individual integrations later

Configuration of Personal Access Tokens

Prerequisites and rules

Prerequisite:

• In the Software Factory, a developer must have created roles and made them available for PATs (see Allow a role for Personal Access Tokens). In IAM, only these roles can be made available to users as permissions they can grant to a PAT.

The following rules apply for PATS for applications:

• A PAT is always created for a single application and pinned to the application alias, for one or more roles (permissions). This allows the PAT to remain valid over multiple versions of the application, as long as the role IDs remain the same and granted to the user. See:
  • Allow PATs in an application
  • Make a role in an application available as permission in PATs
• Users need the right to create PATs. See Authorize a user to create PATs.

For administrative tasks:

• Administrative PATs are only available for Indicium. They may require specific administrator roles.

Allow PATs in an application

main administrator application administrator

Decide for each application and tenant whether you want to allow the creation and use of PATs.

To allow the creation and use of PATs in an application:

menu Authorization > Applications > tab Form

1. Select the checkbox Allow personal access tokens.

Make roles in an application available for PATs

main administrator application owner

If the following conditions are met, you can make roles available as permissions for PATs:

• In the Software Factory, the role is already made available as permission for PATs (see Allow a role for Personal Access Tokens)
• In IAM, PATs are allowed to be used in an application (see Allow personal access tokens in an application)

To make a role available to be used as permission in a PAT in your application:

menu Authorization > Applications > tab Authorization settings > tab Personal access token roles

1. Select a role.
2. Execute the task Set role available for PAT .

Authorize a user to create PATs

main administrator user administrator

To allow users to create and use PATs:

menu Authorization > Users > tab Form

1. Select the checkbox Allow personal access token creation.

note

To allow the creation of administrative tasks in Indicium with a PAT, users need specific roles:

• Health check (advanced): main administrator or developer
• Licensing: main administrator

Create a PAT

user Universal GUI

Only end-users can create PATs. To create a PAT, a user needs to:

1. Open their profile menu and select Create Personal access tokens.
2. Select an Application.
3. Add a Token name.
4. Select an Expiration date. The expiration date can be set from one day to one year. It is not possible to be notified when a PAT is about to expire, so users need to set a reminder themselves or regularly check and extend their PATs. Expiration dates can still be adjusted after they have passed.
5. Select the Permissions they want to assign to the token.
6. Select Create token.
7. Copy the token and save it in a secure location.

warning

The token is shown only once, so users need to copy and save it in a secure location, for example, a password manager. This token needs to be used in the connection to another application.

Create a personal access token for an application

Edit a PAT

user Universal GUI

Users are allowed to edit a PAT. Possible reasons are:

• Expiration date passed - To reactivate a PAT, users can select a new expiration date
• Permissions have been changed by an administrator - To reactivate a PAT, users can edit the permissions or contact the administrator
• Add or remove permissions
• Change the token name

To edit a PAT, a user needs to:

1. Open the profile menu and select Personal access tokens.
2. Select the PAT and edit it.

Revoke a PAT

main administrator user administrator

Only administrators are allowed to revoke a PAT, users can only delete them. See Delete a PAT.

To revoke a PAT:

menu Analysis > Personal access tokens

1. Select the PAT.
2. Execute the task Revoke personal access token .

A PAT cannot be edited or reactivated after it has been revoked .

Revoked personal access token

Delete a PAT

user Universal GUI

To delete a PAT if it is no longer needed or compromised, a user needs to:

1. Open the profile menu and select Personal access tokens.
2. Select the PAT.
3. Select Delete . This action is irreversible.

Delete a personal access token

Overview of personal access tokens

main administrator user administrator

menu Analysis > Personal access tokens

Administrators are not allowed to create PATs, but they can view all PATs in the tenant. If a PAT is compromised, they can revoke it. See Revoke a PAT.

Personal access tokens overview