Personal Access Tokens

Personal Access Tokens (PATs) provide a secure way to authenticate with the Kinesis API programmatically. They allow you to interact with the API without using your username and password, making them ideal for automated scripts, external applications, and CI/CD pipelines.

Understanding Personal Access Tokens

PATs function similarly to passwords but have several advantages:

• Fine-grained Permissions: Limit tokens to specific actions and resources
• Limited Lifespan: Set expiration dates to reduce security risks
• Independent Revocation: Revoke individual tokens without affecting other access methods
• Traceability: Track which token is used for which operations

Accessing the PAT Management Page

To manage your Personal Access Tokens:

1. Log in to your Kinesis API account
2. Navigate to /web/pats in your browser or use the sidebar navigation

Creating a New Token

To create a new Personal Access Token:

1. Click the "Create a New Personal Access Token" button

2. Fill in the required information:

   • Name: A descriptive name to identify the token's purpose
   • Valid From: The date and time when the token becomes active
   • Valid To: The expiration date and time for the token
   • Permissions: Select the specific actions this token can perform

3. Click "Create" to generate the token

Token Display - Important Notice

⚠️ Critical Security Information: When a token is first created, the actual token value is displayed only once. Copy this token immediately and store it securely. For security reasons, Kinesis API only stores a hashed version of the token and cannot display it again after you leave the page.

Managing Existing Tokens

The PAT management page displays all your existing tokens with their details:

• Name: The descriptive name you assigned
• ID: The unique identifier for the token
• Valid From: The start date of the token's validity period
• Valid Until: The expiration date of the token
• Rights: The permissions assigned to the token

Updating Token Details

You can modify several aspects of an existing token:

1. Name: Click the pencil icon next to the token name
2. Valid From: Click the pencil icon next to the start date
3. Valid Until: Click the pencil icon next to the expiration date
4. Rights: Click the star icon to modify permissions

Note: For security reasons, you cannot view or modify the actual token value after creation. If you need a new token value, you must create a new token and delete the old one.

Deleting Tokens

To revoke access for a token:

1. Click the trash icon next to the token you want to delete
2. Confirm the deletion in the modal that appears

Once deleted, a token cannot be recovered, and any applications using it will lose access immediately.

Token Permissions

Kinesis API uses a granular permission system for PATs. When creating or editing a token, you can select specific permissions that control what actions the token can perform:

The available permissions depend on your user role. For example, ROOT users have access to all permissions, while other roles have a more limited set.

Using Personal Access Tokens

To use a PAT in API requests:

GET /user/fetch HTTP/1.1
Host: api.example.com
Authorization: Bearer your-token-here

Include the token in the Authorization header with the Bearer prefix for all authenticated requests.

Best Practices

1. Use Descriptive Names: Give each token a name that identifies its purpose or the application using it
2. Set Appropriate Expirations: Use shorter lifespans for tokens with broader permissions
3. Limit Permissions: Grant only the specific permissions needed for each use case
4. Rotate Regularly: Create new tokens and delete old ones periodically
5. Secure Storage: Store tokens securely, treating them with the same care as passwords
6. Monitor Usage: Regularly review your active tokens and delete any that are no longer needed

Token Security

Personal Access Tokens are equivalent to your password for the granted permissions. To keep your account and data secure:

• Never share tokens in public repositories, client-side code, or insecure communications
• Use environment variables or secure secret management systems to store tokens
• Set expiration dates appropriate to the use case (shorter is better)
• Delete tokens immediately if they might be compromised

Related Documentation

• API Reference - Learn how to use tokens with API endpoints
• Users - Overview of user management
• Security - Additional security considerations