#API Access Tokens Overview
API Access Tokens allow external systems, CI/CD pipelines, automation tools, and integrations to securely access Hawzu APIs without user login.
Tokens are API-only credentials designed for programmatic access and automation use cases.
#What Are Access Tokens?
Access Tokens are:
- Machine credentials for API access
- Non-interactive (no UI login)
- Scoped to workspace or project
- Permission-bound using roles
- Revocable and expirable
They are commonly used for:
- CI/CD pipelines
- Automation frameworks
- Custom scripts
- External system integrations
#Token Scope & Access Type
Each access token is created with a specific scope, which defines where it can be used.
#Workspace Tokens
Workspace tokens grant access across the workspace, based on the assigned workspace role.
Use cases:
- Organization-wide automation
- Admin or audit tooling
- Cross-project analytics
#Project Tokens
An access token can be associated with multiple projects.
For each project, a project-specific role must be selected, and the token’s permissions for that project are strictly limited to the assigned role.
Use cases:
- Project-specific CI pipelines
- Test execution automation
- Release or defect sync jobs
#Access Token List View
The Access Tokens page provides a complete view of all tokens in the workspace.
Each token row shows:
- Label – Human-readable token name
- Status – Enabled or Disabled
- Access Type – Workspace or Project
- Created By – User who generated the token
- Created At – Token creation timestamp
- Expires On – Expiry date (if configured)
- Actions – Manage token lifecycle
#Token Status
Tokens can exist in different states:
#Enabled
- Token is active
- API requests are allowed
#Disabled
- Token is inactive
- All API requests are rejected
- Useful for temporary suspension
#Token Expiry
Tokens can optionally have an expiry date.
- Expired tokens automatically stop working
- Expiry is clearly highlighted in the UI
- Tokens without expiry show Not Specified
Recommended: Always set an expiry for automation tokens.
#Token Visibility & Security
#One-Time Token Value
- Token value is shown only once at creation
- After closing the modal, the token cannot be retrieved again
- You must regenerate the token if lost
#Secure by Design
- Tokens are hashed at rest
- Hawzu never stores plain token values
- All token actions are logged in audit logs
#Token Lifecycle Actions
From the Actions menu, you can:
- Edit – Update label, expiry, or role (if allowed)
- Enable / Disable – Temporarily suspend access
- Delete – Permanently revoke the token
Deleting a token immediately invalidates all API access using it.
#Roles & Permissions
Access tokens do not have permissions directly.
Instead, permissions are derived from:
- Assigned Workspace Role (for workspace tokens)
- Assigned Project Role (for project tokens)
This ensures:
- Consistent permission behavior
- Centralized access control
- Safe role-based access enforcement
#When to Use Access Tokens
Use access tokens when:
- Automation needs Hawzu API access
- No human interaction is involved
- Security and auditability are required
- CI/CD pipelines need scoped access
Avoid using tokens for:
- Interactive user sessions
- UI-based access
- Sharing between individuals
#Best Practices
#Naming
- Use descriptive labels
Example: ci-release-runner, nightly-tests-bot
#Scope Minimization
- Prefer project tokens over workspace tokens
- Assign least-privilege roles
#Expiry
- Always set an expiry date
- Rotate tokens regularly
#Monitoring
- Disable unused tokens
- Periodically audit active tokens
#Ownership
- Clearly document which system owns each token
- Avoid “shared” or ambiguous tokens
#Next Steps