# 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 - Portable agent skill: https://tokensand.com/agents/install/SKILL.md - OpenAPI: https://tokensand.com/openapi.json - LLM guide: https://tokensand.com/llms.txt - Full LLM context: https://tokensand.com/llms-full.txt ## Live Enterprise evidence in coding agents In native Enterprise Settings → API keys, an authorized owner/admin selects Agent read-only and a product. The key expires within 90 days and can be revoked. Configure DAI_ENTERPRISE_TOKEN privately in the MCP host and set --mode enterprise. Browser sign-in and DAI_TOKEN do not grant this access. Call get_enterprise_context, then get_enterprise_report(productId, periodDays:7–365) or get_enterprise_actions(productId, limit:1–20). These reads use current product/plan authority and create audit receipts. They cannot ingest, export jobs, approve, send or execute actions. Paid reports/actions remain paid; missing sources remain unknown. Preserve evidence grades, reporting dates and truncation notices. enterprise_session_brief(live:true, productId) uses the live report; ordinary briefs analyze supplied/sample metrics. ## 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 an unscoped developer token when a signed-in developer wants a coding agent to fetch a build packet, import an Agent Skill draft from SKILL.md, draft project proof, or publish project proof after explicit approval. Use a project-scoped token only for private reads tied to one existing project. - Token issuer: https://tokensand.com/api/workflow/mcp-config - Browser generator: https://tokensand.com/projects/new#editor-workflow - Token listing: https://tokensand.com/api/workflow/tokens - Token format: Bearer token with prefix dai_ - Token transport: Authorization: Bearer YOUR_WORKFLOW_TOKEN - Developer-token scopes: project:read, tools:read, project:publish - Project-token scopes: project:read, tools:read; project creation and Agent Skill import are forbidden - Context endpoint: https://tokensand.com/api/workflow/context - Build packet endpoint (developer tokens only): https://tokensand.com/api/workflow/build-packet - Agent Skill draft import endpoint: https://tokensand.com/api/workflow/agent-skills - 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 same generator panel 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. ### Private provider credit balances For Tavily, GET https://tokensand.com/api/me/usage/providers/tavily reads the owner's saved snapshot with an account-level project:read token. POST to the same endpoint with project:publish scope and JSON {apiKey,lastRun?} checks the provider's credit counters. lastRun may contain occurredAt (required), requestId, credits, durationMs and applicationName. Project-scoped tokens cannot read or sync account balances. Keep TAVILY_API_KEY and DAI_TOKEN in server environment variables. Tokens& uses the provider key transiently over HTTPS and never persists it. Never pass key values in a coding-agent prompt, public source, browser bundle or usage metadata. No query, result, prompt or customer data is needed. Signing up with a provider or connecting a catalog tool does not automatically sync its balance. After a successful search, sync its minimal run metadata. Coalesce syncs to at most one per 90 seconds and honor Retry-After: Tokens& allows eight per ten minutes; Tavily also limits usage reads. A sync failure must never trigger another Search. GET reads and account-level get_context in the Agent Pack use stored snapshots without provider calls. Omit projectId when requesting account balances. Provider counters may lag completed searches. checkedAt records when the API was read, not a guarantee recent calls are included. Keep local credit reservations until the counters reflect them. Credits are account/key totals, latest run details are client-reported, and billed dollars remain unknown. Private provider snapshots are separate from vendor-shared receipts and public adoption evidence. For Bright Data, GET https://tokensand.com/api/me/usage/providers/brightdata reads only the owner's saved balance as {snapshot}, with null when absent. Use an account-level project:read token or authenticated browser session. POST to the same endpoint requires account-level project:publish or a same-origin browser session and accepts only JSON {apiKey}; the trimmed key must be 16–512 letters, digits, underscores or hyphens. POST returns {snapshot,updated}; updated:false retains a newer saved snapshot. Project-scoped tokens are forbidden. Keep BRIGHT_DATA_API_KEY in a private local/server environment, never prompts, public source, a browser bundle or logs. An explicitly entered dashboard key is sent transiently to the server and is not saved. Each Bright Data sync sends one GET to the fixed https://api.brightdata.com/customer/balance endpoint with an eight-second timeout, no redirects and no automatic retries. Tokens& permits eight syncs per account per ten minutes; honor Retry-After. Only sanitized numeric balances, an explicitly reported supported currency, and checkedAt are saved; no credentials, invoice contents, raw responses or customer data are persisted. Responses are private, no-store. The snapshot uses provider:"brightdata" and source:"provider_api", with balance:{amount,pendingAmount,currency}, freeTier:{remainingRequests:null,limit:null}, and spending:{billedUsd:null}. Missing amounts and currency stay null. A balance lookup cannot establish remaining free MCP requests, a redeemed perk, verified product use or monthly billed spend. pendingAmount is the provider's pending amount, not a monthly bill. Record separately confirmed monthly Bright Data charges through the monthly-spend endpoint; never infer them from the balance or pending amount. ### Consented tool usage receipts The builder enables sharing at https://tokensand.com/dashboard/usage?mode=developer. Only the authenticated browser can create or renew that connection. Sending a receipt never reconnects a tool after disconnection or a vendor ownership change. GET https://tokensand.com/api/me/usage requires account-level project:read; POST requires account-level project:publish. Send toolId or toolSlug, receiptType, and the actual operation's idempotencyKey. Reuse that key for every receipt retry; never repeat the provider call to repair reporting. Include only known success, durationMs and spendCents; credits are not currency. Optional projectId must be an owned published project that lists this tool. Never include secrets, queries or customer data. Responses distinguish queued, vendor_unlinked, existing_receipt and relay_unavailable. A queued receipt is not confirmed delivery. sharedWithVendor means consent at admission; vendorOrganizationLinked and reconnectRequired describe the connection. A vendor sees only authorized self-reported evidence, never private provider balances. These receipts do not establish verified activation, retention or revenue. ### Private monthly charges and Codex allowance GET https://tokensand.com/api/me/usage/spending reads private monthly amounts and the saved Codex allowance. Optional ?month=YYYY-MM selects a current or earlier UTC month. Account-level project:read is required; project-scoped tokens are forbidden. POST with account-level project:publish accepts one of: - {type:"monthly_spend",provider:"codex"|"tavily"|"brightdata",month:"YYYY-MM",currency:"USD"|"MXN"|"EUR"|"GBP",amountCents:,source:"user_reported"|"agent_reported"}. This replaces the provider/month/currency total. Codex includes the ChatGPT subscription and extra credit purchases; OpenAI API bills are separate and must not be entered in this bucket. Record only authorized, observed billing amounts. Never sum different currencies or add per-call receipts, provider balances, pending amounts or credit estimates to these totals. - {type:"codex_snapshot",checkedAt:,planType:,creditsBalance:,primary:{usedPercent:,windowDurationMins:,resetsAt:},secondary:}. Use the signed-in Codex account's supported usage tool. Missing fields stay null. This is an agent-reported snapshot, not a live provider connection or a monetary bill. A zero credit balance does not mean zero spending. DELETE accepts {type:"monthly_spend",provider,month,currency} or {type:"codex_snapshot"}. Monthly data is bounded to 24 entries per provider/currency. Original totals remain grouped by currency with partial coverage; unrecorded bills remain unknown. The derived usdEstimate is a USD view, never a new payment record. Non-USD amounts use dated European Central Bank reference rates from https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml (one-hour public cache; dates older than seven days rejected). Conversion uses USD-per-euro divided by original-currency-per-euro, rounded to cents per recorded entry. The original amount/currency is unchanged. These are reference estimates, not historical card or invoice FX; additional bank FX fees are not estimated. totalCents is null if any entry cannot convert; knownSubtotalCents is partial, never a total. Read-only account context may fetch this fixed public feed, with no account/bill details sent. USD-only or explicit zero needs no FX lookup. Compact workflow context preserves every monthlyEntries field and adds usdCents there; it omits the duplicated usdEstimate.entries array. Full context and the spending API retain that derived array. codexCreditReferenceValue and provider creditReferenceValue are separate noncash USD reference estimates. Supported personal Codex plans use the published 2,500-credits/US$100 equivalence, with account/region prices varying (https://developers.openai.com/community/students). Researcher credits use Tavily's published US$0.008 PAYGO equivalence (https://docs.tavily.com/documentation/api-credits). Unknown/unsupported balances remain unavailable. Never add these references to monthly charges or calculate dollars from an allowance percentage. Stored accountSpending is available in account-level workflow context, never vendor dashboards or public/project context. Never upload OpenAI credentials, cookies, invoice links, payment details, prompts or conversations. This endpoint does not purchase credits or change subscriptions. ### 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. - Contract evidence: public tracking metadata, including caller-selected IMPORT and repository receipt or verification fields, cannot create paid quarterly repository evidence. Those attestation fields are removed recursively. An active repository count requires a fresh receipt written by a server-side authenticated GitHub provider callback; raw repository URLs remain context only. ### Deterministic intake automation Use this when a company submits public perk or hackathon partner materials. Deterministic automation validates evidence, triages the submission, and prepares private drafts for partner workspace access, tracked docs/perk links, Hackathon Passport details, and product/API usage tracking setup. It does not publish or provision anything. A signed-in, authorized human must review and approve every draft before publication or provisioning. ## 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. Read https://tokensand.com/agents/install/SKILL.md when the host supports portable skills or persistent project instructions. 3. Use public endpoints for discovery and aggregate reads. 4. Ask the human to sign in before requesting workflow-token or tracking-key creation. 5. Prefer dry-run validation before production writes. 6. Treat project publishing, launch recording, CRM/export actions, and public proof as approval-gated. 7. 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