App Tokens

App Tokens provide programmatic API access for applications and services. They serve as both an authentication mechanism (identifying the caller) and an authorization mechanism (determining what the caller can do through directly assigned authorities).

Overview

While human users authenticate through the configured authentication provider, automated systems — CI/CD pipelines, integrations, scripts — need a different mechanism. App Tokens fill this role by providing a static credential that carries specific permissions.

Unlike users, who receive permissions through roles, App Tokens have authorities assigned directly. This gives administrators fine-grained control over exactly what each token can do.

App Tokens:

• Are created and managed by administrators (@AdminOnly)
• Have authorities assigned directly
• Use a bearer token format for API authentication
• Are audited (creation and changes are tracked)

Token Structure

An App Token consists of:

Component	Description
name	A human-readable identifier for the token
tokenId	A 16-character hex string derived from the SHA-256 of the secret (first 8 bytes)
secret	A 32-byte random value (base64url-encoded), generated at creation time

The bearer token format is:

AppToken <tokenId>.<secret>

WARNING

The secret is only returned once, at the moment of creation. It is stored hashed in the database and cannot be recovered. If lost, the token must be regenerated.

Creating an App Token

App Tokens are managed via the Management section in the UI (admin-only). When you create an App Token:

1. Provide a name for identification
2. Assign one or more authorities directly to define the token's permissions
3. The system generates a random secret and returns the full bearer token
4. Copy and store the token immediately — it will not be shown again

Using an App Token

Include the token in the Authorization header of your API requests:

GET /api/products HTTP/1.1
Authorization: AppToken a1b2c3d4e5f6g7h8.dGhlLXNlY3JldC12YWx1ZS1oZXJl

The token is validated by:

1. Extracting the tokenId from the header
2. Looking up the App Token record by tokenId
3. Verifying the provided secret against the stored hash
4. Resolving the token's directly assigned authorities

Permissions

App Tokens have authorities assigned directly, rather than through roles. The token's effective permissions are exactly the set of authorities assigned to it. The same access evaluation pipeline applies — including @AdminOnly checks, @OwnerField filtering, and sensitive field masking.

Security Considerations

• Treat App Tokens like passwords — store them securely (e.g., in a secrets manager or environment variable)
• Use least privilege — assign only the authorities necessary for the token's purpose
• Rotate regularly — delete and recreate tokens periodically
• Audit usage — App Token operations are tracked through Squizy's auditing system