# tokens& auth.md

> Agent-auth and credential discovery guide for tokens&. This file is public, machine-readable, and intentionally conservative.

tokens& supports agent-assisted developer and enterprise workflows through authenticated sessions, scoped workflow tokens, customer-issued tracking keys, and deterministic intake automation. tokens& does not currently support anonymous agent account creation, ID-JAG identity assertion registration, or unauthenticated agent-issued credentials.

## Service
- Public website: https://tokensand.com
- Authenticated workspace: https://tokensand.app
- API documentation: https://tokensand.com/docs/api
- OpenAPI: https://tokensand.com/openapi.json
- LLM guide: https://tokensand.com/llms.txt
- Full LLM context: https://tokensand.com/llms-full.txt

## Supported credential flows

### Authenticated browser session
Use this when a user is creating a developer profile, company workspace, tracking key, MCP/Codex/Cursor config, or public proof.

- Sign in: https://tokensand.com/login
- Sign up: https://tokensand.com/register
- Dashboard: https://tokensand.app/dashboard
- Security boundary: private dashboard, company workspace, billing, exports, and reports require an authenticated user session.

### Developer workflow token
Use this when a signed-in developer wants a coding agent to read scoped project context, fetch a build packet, draft project proof, or publish after explicit approval.

- Token issuer: https://tokensand.com/api/workflow/mcp-config
- Token listing: https://tokensand.com/api/workflow/tokens
- Token format: Bearer token with prefix dai_
- Token transport: Authorization: Bearer YOUR_WORKFLOW_TOKEN
- Token scopes: project:read, tools:read, project:publish
- Context endpoint: https://tokensand.com/api/workflow/context
- Build packet endpoint: https://tokensand.com/api/workflow/build-packet
- Project draft endpoint: https://tokensand.com/api/workflow/projects/draft
- Publish endpoint: https://tokensand.com/api/workflow/projects
- Revocation: signed-in users can revoke workflow tokens from the dashboard or via the token revocation endpoint.

Workflow tokens are shown once, stored hashed, scoped to the user or project, rate-limited, revocable, and never grant access to another user or tenant.

### Enterprise tracking key
Use this when an enterprise customer wants a server-side system or approved agent workflow to send usage/adoption events.

- Dry-run endpoint: https://tokensand.com/api/usage/track/dry-run
- Production endpoint: https://tokensand.com/api/usage/track
- Batch endpoint: https://tokensand.com/api/usage/track/batch
- Token transport: Authorization: Bearer YOUR_TRACKING_KEY
- Required boundary: keep tracking keys server-side.
- Privacy boundary: public outputs are aggregate or source-labeled. Raw developer resale is not the product.
- Event coverage: product usage tracking, docs usage tracking, credit/perk claims, repo/build signals, submission milestones, retention checks, and account-intent updates.

### Deterministic intake automation
Use this when a company submits public perk or hackathon partner materials. The intake agent can auto-approve public-safe company-domain evidence, provision partner workspace access, prepare tracked docs/perk links, attach partner details to the Hackathon Passport, and route product/API usage tracking setup back to the company workspace. Ambiguous submissions stay in needs-info or review-required state.

## Not supported
Do not assume tokens& supports these flows unless a future version of this file says so:

- Anonymous agent registration that returns credentials without a signed-in user or approved company workspace.
- ID-JAG or other third-party identity assertion acceptance.
- OTP claim flow where an agent creates an account first and a human claims it later.
- Autonomous CRM writes, public publishing, repo actions, or external workflow writes without explicit human approval.
- Cross-tenant reads, raw developer identity resale, private report access, or private enterprise metrics through public endpoints.

## Agent behavior
Agents should:

1. Read https://tokensand.com/llms.txt and https://tokensand.com/openapi.json before calling APIs.
2. Use public endpoints for discovery and aggregate reads.
3. Ask the human to sign in before requesting workflow-token or tracking-key creation.
4. Prefer dry-run validation before production writes.
5. Treat project publishing, launch recording, CRM/export actions, and public proof as approval-gated.
6. Cite source labels and confidence when generating enterprise adoption or ROI answers.

## Rate limits and errors
All credential and tracking endpoints are rate-limited. Agents should honor 401, 403, 429, and quota metadata, avoid retry storms, and surface missing-auth or missing-scope errors to the human.

## Contact
- Enterprise adoption platform: https://tokensand.com/platform
- API docs: https://tokensand.com/docs/api
- Security: https://tokensand.com/security
- Privacy: https://tokensand.com/privacy