#Create Access Token - API Authentication Guide
Access Tokens allow external systems, CI/CD pipelines, integrations, and scripts to securely access Hawzu APIs without using a user’s login credentials.
This guide explains how to create access tokens, configure their scope, assign permissions, and manage expiration securely.
#What Are Access Tokens?
Access tokens are API-only credentials used for programmatic access.
They:
- Do not grant UI access
- Are scoped by workspace or project
- Use role-based permissions
- Can be time-bound or permanent
- Are shown only once at creation time
#Access Token Types
Hawzu supports two types of access tokens:
#Workspace Tokens
- Apply at the workspace level
- Use a workspace role for permissions
- Suitable for:
- Admin tooling
- Auditing
- Cross-project automation
- Integrations requiring workspace metadata
#Project Tokens
- Apply to one or more projects
- Each project has its own assigned project role
- Suitable for:
- CI/CD pipelines
- Automation scripts
- Test execution integrations
- Project-specific tooling
Important
Project access is evaluated independently per project.
The token cannot exceed the permissions of the role assigned to that project.
#Creating an Access Token
#Step 1: Open Create Token
- Navigate to Settings → Access Tokens
- Click Create Token
The Create Access Token modal opens.
#Step 2: Enter Token Details
Token Name (Required)
- A descriptive name to identify the token
- Examples:
CI RunnerNightly AutomationZapier Sync
This name helps track usage and audit access later.
#Step 3: Choose Token Scope
Select one of the following:
Your selection determines the permissions model shown next.
#Creating a Workspace Token
When Workspace is selected:
- Choose a Workspace Role
- Example roles:
- Workspace Manager
- Workspace Coordinator
- Workspace Member
- Workspace Viewer
- The token inherits all permissions of that role
- Permissions apply across the workspace
Use Workspace Tokens when:
- You need read/write access across multiple projects
- You are integrating admin or reporting tools
- You require workspace-level metadata access
#Creating a Project Token
When Project is selected:
- Add one or more projects
- For each project:
- Select the project
- Assign a project role
- Repeat using Add another project if needed
Key Behavior
- A single token can be linked to multiple projects
- Each project has its own role
- Permissions do not merge or escalate across projects
Example
- Project A → Project Manager
- Project B → Project Viewer
The token has:
- Full access in Project A
- Read-only access in Project B
#Setting Token Expiry
You can set an expiration for every token:
- 1 Week
- 1 Month
- 6 Months
- 1 Year
- Custom Date
- Never Expires
Best Practice
- Prefer short-lived tokens for automation
- Avoid “Never Expires” unless strictly required
Expired tokens automatically stop working.
#Creating the Token
- Review the configuration
- Click Create Token
- The token value is generated
⚠️ Important Security Notice
This is your one and only chance to copy the token value.
Once you close this window, the token cannot be viewed again.
Store it securely in:
- Environment variables
- Secrets manager
- CI/CD secret store
#After Creation
Once created, tokens appear in the Access Tokens list showing:
- Token name
- Access type (Workspace / Project)
- Assigned projects and roles
- Creator
- Created date
- Expiry status
- Enabled / Disabled state
You can:
- Disable tokens temporarily
- Revoke tokens permanently
- Rotate tokens by creating a new one
#Security Best Practices
- Use one token per integration
- Assign the minimum required role
- Avoid sharing tokens between systems
- Set expiry dates whenever possible
- Revoke unused or compromised tokens immediately
- Rotate tokens periodically
#Common Use Cases
#CI/CD Automation
- Project token
- Project role: Project Member or Coordinator
- Short expiry (1–3 months)
#Test Execution Pipelines
- Project token
- Role scoped to executions only
- Linked to relevant test projects
#Reporting & Analytics
- Workspace token
- Workspace Viewer role
- Read-only access
#Next Steps