Machine authentication
Designing a secure PAT architecture for Product
The problem
CLI clients, automation, and external integrations cannot use a browser session, but still need durable API credentials that are revocable, scoped, auditable, and isolated to an organization.
The solution
Added Personal Access Tokens as a separate authentication path. The BFF generates and hashes each token, validates it at the external boundary, and passes trusted identity context to internal APIs.
The result
Machine clients can authenticate without browser sessions or Auth0 credentials, while token lifecycle controls and backend authorization keep access bounded and traceable.
System architecture
Architecture draftArchitecture decision
A credential for non-browser clients
Browser sessions use Auth0 through the BFF, but a CLI, deployment pipeline, or external integration has no browser session to present. A separate Product-issued PAT gives these clients a credential designed for API requests without turning browser sessions into automation secrets. The PAT is validated by BFF Auth, not as an Auth0 access token.
Clients send the PAT as a Bearer credential. The BFF remains the external authentication boundary, and successful authentication converges on the same backend authorization model used by browser requests.
Architecture decision
Generate once, store a hash
When a user creates a token, the BFF generates a cryptographically random secret with a recognizable prefix such as mt_live_. It stores a SHA-256 hash and token metadata in PostgreSQL, then returns the raw PAT once to the user.
The raw value is not recoverable from the database. If it is lost, the user creates a replacement rather than retrieving the original credential.
Architecture decision
Keep the token lifecycle manageable
Each record is associated with a user and organization, and can include scopes, a display prefix, creation and last-used timestamps, an expiration time, and a revocation timestamp. PostgreSQL is the durable source of truth for these records; Redis remains suited to short-lived state such as sessions and rate limits.
A token is rejected if it is unknown, expired, or revoked. Expiration limits its useful lifetime, and explicit revocation disables it immediately without affecting other credentials owned by the user.
Architecture decision
Validate at the authentication boundary
For each request, the BFF extracts the Bearer PAT, hashes it, looks up the matching record, and checks expiration and revocation before accepting it. Invalid credentials stop at the boundary with 401 Unauthorized.
After validation, the BFF forwards trusted identity context rather than the raw token. Internal APIs and agent services therefore do not need to process or propagate the external secret.
Architecture decision
Authentication is not authorization
A valid PAT proves that the request has a recognized Product credential; it does not grant every permission available to its owner. The BFF carries user, organization, token, and scope context to backend APIs, where scope checks and Casbin RBAC still decide whether an operation is allowed.
Organization context prevents a token from crossing tenant boundaries. Audit events can include the user, organization, token ID, operation, timestamp, and result, making activity traceable to the specific credential used.