Sentinel Pass

A Sentinel Pass is an OAuth 2.0 credential for autonomous agents. It lets an agent — yours, a CI job, or a third party — call Traylinx APIs on behalf of a project without using a human session. Each pass has a client ID, a client secret, a scope set, validity dates, and live usage metrics.

Use a Sentinel Pass when: - An agent or service needs ongoing access to a project's APIs. - You want per-agent metrics, activity logs, and revocation. - A simple project API key doesn't fit because you need OAuth scopes or per-call accounting.

1. Open Sentinel Pass management

1. Open the project: Admin → Projects → {your project}.
2. Open the API Access tab.
3. Switch to the Sentinel Passes sub-tab.

You see one card per pass with name, status, scopes, and last-used timestamp.

2. Create a pass

1. Click Create Sentinel Pass.
2. Fill in:
3. Agent name — appears in metrics and audit logs.
4. Description — what this agent does.
5. Scopes — comma-separated permissions (read:data, write:data, admin:users, etc.). Grant only what the agent needs.
6. Validity period — valid_from and valid_until. Default expiry is one year.
7. Click Create.
8. Copy the client_secret immediately. It is shown once and cannot be recovered. The client_id is always visible from the detail view.

3. The detail view

Open any pass to see four tabs:

• Overview — total requests, success rate, average latency, last used.
• Permissions — scope list with descriptions; edit to add or revoke scopes.
• Usage — timeline chart and activity log with date filtering. Export up to 10,000 records per range as CSV.
• Settings — toggle active/paused, regenerate credentials, edit metadata, or delete.

Metrics refresh automatically every 30 seconds. After three consecutive refresh failures, polling pauses; reopen the page to resume.

4. Use the credentials

The pass exchanges client_id and client_secret for short-lived access tokens via the standard OAuth 2.0 client-credentials flow. See the Sentinel Pass API reference for endpoints and example exchanges.

Store credentials in a secure secret manager. Never commit them to source control.

5. Pause, regenerate, or delete

• Pause — flips the status toggle to inactive. Token exchanges fail; existing tokens remain valid until expiry.
• Regenerate — issues a new client_secret and invalidates the old one. The agent stops working until you redeploy with the new secret.
• Delete — removes the pass entirely. All existing tokens are invalidated immediately.

6. Scope changes

Edit scopes from the Permissions tab. Scope changes take effect on the next token exchange. Cached tokens keep their original scope until they expire.

For project-level keys without OAuth semantics, see API keys. For human sign-in, see Authentication.

---

_{Mirrored from traylinx-web:docs/user-manuals/security/sentinel_pass.md. Edit the source in the traylinx-web repo — changes here are overwritten by the sync script.}