Access Token Management
Create, scope, rotate, and revoke the Bearer tokens that control API access.
Every request to Portway requires a Bearer token. Tokens are managed in the Web UI under Access Tokens (/ui) and are never stored in plaintext, only a PBKDF2-SHA256 hash is persisted.
WARNING
Save the token value shown at creation time. It is only displayed once and cannot be retrieved later.
Creating a token
- Open the Web UI and navigate to Access Tokens
- Click New Token
- Fill in the fields:
| Field | Required | Description |
|---|---|---|
Username |
Yes | Identifies the service or user this token belongs to. Used for audit trail and logging. |
Description |
No | Human-readable purpose note (e.g., "ERP sync service") |
Allowed Scopes |
No | Endpoint access restriction. Default * = all endpoints. |
Allowed Environments |
No | Environment access restriction. Default * = all environments. |
Expires In (days) |
No | Leave blank for a non-expiring token. |
- Click Create and copy the token value immediately.
Scoping tokens
Narrow a token's access to reduce exposure. A token can only access endpoints and environments that match both its scope and the endpoint's own AllowedEnvironments / IsPrivate settings.
Endpoint scopes
| Pattern | Grants access to |
|---|---|
* |
All endpoints |
Products |
Single endpoint named Products |
Products,Orders |
Two named endpoints |
Product* |
All endpoints with a Product prefix |
Company/Employees |
Specific namespaced endpoint |
Company/* |
All endpoints under the Company namespace |
GET:Products |
Products endpoint, GET method only |
Environment scopes
| Pattern | Grants access to |
|---|---|
* |
All environments |
prod |
Single environment |
dev,test |
Two named environments |
dev* |
All environments with a dev prefix |
Common configurations
| Scenario | Scopes | Environments |
|---|---|---|
| Full-access admin token | * |
* |
| Read-only reporting service | GET:* |
prod |
| Single integration (Globe+) | Company/* |
500,700 |
| Development testing | * |
dev,test |
| Webhook ingestion only | webhooks/* |
* |
Rotating a token
Rotation replaces an existing token with a new one while keeping the username, scopes, and environments intact. The old token is revoked immediately.
- Open Access Tokens and find the token to rotate
- Click Rotate
- Copy the new token value
- Update every application or service using the old token
Use rotation on a schedule (e.g., quarterly) or immediately when a token may have been exposed.
Revoking a token
Revocation permanently invalidates a token. Any request using it will immediately receive 401 Unauthorized.
- Open Access Tokens and find the token
- Click Revoke
- Confirm the action
Revocation is irreversible. Create a new token for any user or service that was using the revoked one.
Token audit log
Every token records a history of operations (created, used, rotated, revoked), accessible from the Access Tokens page by clicking Audit on a token row. This log is also queryable directly:
GET /ui/api/tokens/{id}/auditSee Token Audit Log for the schema.
First-run token
On first startup, Portway writes an initial token to tokens/{SERVER_NAME}.txt. This token has full access (* scopes, * environments). Delete the file from disk immediately after recording the value, then use the Web UI for all subsequent token management.
Related
- Authentication reference: validation flow, error responses, scope syntax
- Security guide: incident response, network restrictions, encryption
- Web UI: enabling and configuring the management interface