-
-
Notifications
You must be signed in to change notification settings - Fork 0
User API Keys
The API Keys page (/api-keys) — accessible to tenant admins and super admins — lets you generate and manage API keys for programmatic access to the mate REST API.
API keys allow external tools, CI/CD pipelines, and scripts to interact with mate without browser-based authentication. Each key has a defined scope limiting what it can do.
- Navigate to API Keys (
/api-keys). - Click Generate Key.
- Enter a Name (e.g.
ci-pipeline,integration-tests). - Select the Role:
| Role | Permissions |
|---|---|
| Viewer | Read-only access |
| Tester | Viewer access + execute test runs |
| TenantAdmin | Full tenant-level management |
| SuperAdmin | Full global access |
- Click Generate.
- Copy the key immediately — the full key value is only shown once. It is stored as a SHA-256 hash.
Include the key in all API requests via the X-API-Key header:
GET /api/agents HTTP/1.1
Host: your-mate-instance
X-API-Key: your-api-key-hereOr via Authorization: ApiKey:
Authorization: ApiKey your-api-key-hereThe API Keys page includes an API Explorer section with quick links:
- Scalar UI — opens interactive API documentation.
-
OpenAPI JSON — downloads the OpenAPI specification file (
mate-openapi.json).
Use these shortcuts to inspect endpoints and test authenticated requests right after key generation.
- Revoke — disables the key immediately. It remains in the list as revoked (audit trail preserved).
- Delete — permanently removes the key record.
To revoke: click the Revoke button next to the key. To delete: click the Delete button.
All key operations (generate, revoke, delete) are recorded in the Audit Log.
- Never commit API keys to source control.
- Use the lowest-privilege scope sufficient for the task.
- Rotate keys regularly; revoke any key that may have been exposed.
- Keys are stored as SHA-256 hashes — mate cannot recover a lost key.
- Developer API Reference — REST endpoint documentation
- Audit Log — review key usage events