Personal Access Tokens

Personal Access Tokens (PATs) let you authenticate with the Management API without a browser sign-in. They're meant for scripts, CI/CD pipelines and other automation, including the Agility CLI. Each PAT acts as the user who created it, with that user's permissions on every Agility instance they can reach. A token expires on the date you set, at most two years after you create it, and each user can have up to 10 active tokens. A token is tied to the user who created it: when that user is suspended or removed, their tokens stop working.

Creating and Managing PATs

There's no screen for tokens in the Agility app yet: you create and manage them with the Management API. For step-by-step commands you can copy and paste, see Create a Personal Access Token. The endpoints are also listed under Personal Access Tokens in the Management API reference.

PAT Usage Rules and Limitations

Token Creation

• Personal Access Tokens can only be created by users authenticated via OAuth.
• A Personal Access Token cannot be used to create additional personal access tokens.
• The token secret is displayed only once during creation and cannot be retrieved afterward.
• Token names and expiration dates remain viewable after creation.

Token Scope and Permissions

• Each token operates on behalf of the user who created it.
• Tokens inherit the same permissions as the creating user.
• Personal Access Tokens do not have separate role-based access controls.
• If the user's permissions change, the token's access changes accordingly.

Restricted Operations

• Personal Access Tokens cannot be used to create or update users.

Token Lifecycle

• Maximum token lifetime is 2 years from creation date.
• Each user can have up to 10 active tokens.
• Tokens automatically expire after their expiration date.
• You can disable or delete your own tokens at any time. See Manage your tokens.
• Expired or revoked tokens cannot be restored or renewed.

Security Considerations

• Token secrets are sensitive credentials and should be stored securely.
• Use environment variables or secure secret management systems to store PATs.
• Never commit tokens to version control.
• Regularly rotate tokens for enhanced security.
• Revoke unused or unnecessary tokens.

Best Practices

• Create separate tokens for different applications or purposes.
• Use descriptive names that indicate the token's purpose.
• Set appropriate expiration dates based on your use case.
• Monitor token usage and revoke any tokens showing suspicious activity