Description
Scoped Agent Credentials give each automated principal its own revocable authentication material. When an administrator issues a credential, Dots generates a raw token once, stores only its hash and a non-secret prefix, and can apply both an expiration time and a permission-scope subset. Requests authenticated with that token resolve to the bound agent principal, then intersect the credential scope with the principal’s current role and grant authority.
This design separates identity administration from token lifecycle. Rotating or revoking a credential does not require recreating the agent, while changing the agent’s grants immediately affects all of its credentials. The raw secret is returned only at issuance, making copy-once handling explicit and preventing later management reads from exposing usable bearer material.
Selling Points
- Avoids shared human API keys by giving every agent a distinct, attributable credential.
- Narrows a token below the agent’s full authority, reducing the impact of leakage or use outside its intended workflow.
- Supports expiry and revocation for routine rotation and incident response.
- Stores no recoverable raw token, limiting credential exposure in database reads and management screens.
- Keeps authorization dynamic: later role or grant changes apply without reissuing every credential.
User Story
An administrator provisions an ingestion agent with broad read access but issues a credential scoped only to the atoms needed by one scheduled job, expiring in thirty days. They copy the token into the job’s secret store and can later revoke it from Access settings. The administrator walks away with a bounded credential whose actions remain attributable to the agent principal.
Extension Surface
This capability is automatable. Credential issue, listing, and revocation are exposed through packages/api/src/routes/access.ts, with validation and authority intersection in packages/access/src/service.ts. Token generation and hashing ride the internal CredentialCodecLike seam in packages/access/src/contracts/access-like.ts, but no supported external credential-format plugin is published.
Capabilities & Limits
- Issues hashed bearer credentials bound to one agent principal.
- Supports optional expiration and permission-scope narrowing.
- Lists safe credential metadata and revokes credentials without deleting the agent.
- Raw token material is available only once and cannot be recovered later.
- A scoped credential can only remove authority; it cannot grant an atom the principal lacks.
Implementation Map
packages/access/src/contracts/access-like.tspackages/access/src/service.tspackages/db/src/schema/access-credentials.tspackages/api/src/routes/access.ts