Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.auditynow.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

Audity uses Bearer token authentication for all agent API calls. The token is a Personal Access Token (PAT) you generate from your Audity settings page. Every API request must include: 
Authorization: Bearer aky_<your-token>
A PAT resolves to your Clerk user identity in middleware. From there, every request is gated by exactly the same stack that protects the web app:
  • Subscription tier, gates which features are callable
  • Supabase Row-Level Security, you only ever see rows your user_id owns
  • Credit balance, write operations that cost credits deduct from your balance
  • Rate limits, per-token
There is no separate permission model for agents.

​
Token format

aky_<32 random base62 characters>
The aky_ prefix is reserved. The middleware uses it to distinguish PATs from Clerk session JWTs without doing a database lookup on every request. Tokens are stored as bcrypt hashes plus an HMAC lookup digest. The plaintext leaves the database after creation and is never written to logs.

​
Generating a token

  1. Sign in at app.auditynow.com
  2. Go to Settings → API Tokens
  3. Click Create Token
  4. Choose:
    • Label, a human-readable name (e.g., Claude on my MacBook, n8n production)
    • Scopes, read, write, or both
    • Expiry (optional), set an expiry date or leave blank
  5. Click Create
  6. Copy the token immediately, it will not be shown again
We cannot recover a lost token. If you lose one, revoke it and create a new one.
You can have up to 10 active tokens per user. Creating an 11th returns 409, revoke an old one first.

​
Scopes

ScopeWhat it allows
readAll GET requests on agent-allowlisted routes
writeAll POST / PATCH / DELETE on agent-allowlisted routes (also implicitly grants read)
adminReserved for future team-level operations. The middleware accepts the scope today but no route requires it.
For most integrations, read + write is what you want. Use read only for read-only dashboards or reporting where the agent should never spend credits or mutate state. GET, HEAD, and OPTIONS requests don’t require a scope (read is implicit). POST, PATCH, and DELETE require write.

​
What’s exposed to PATs (the agent surface)

The PAT-accessible route allowlist is intentionally narrow. As of v1:
  • GET /api/user/current, GET /api/user/tier, GET /api/user/credits
  • GET /api/projects, POST /api/projects
  • GET /api/projects/{id}, PATCH /api/projects/{id}
  • POST /api/projects/{id}/audit-analysis, GET /api/projects/{id}/audit-analysis
  • GET /api/projects/{id}/opportunities
  • GET /api/projects/{id}/deliverables
  • GET /api/lead-generation/leads, GET /api/lead-generation/leads/{id}
  • POST /api/lead-generation/leads/{id}/convert
  • All /api/nucleus/{captures,memories,contacts,insights,suggestions} endpoints documented in the API Reference
Routes outside the allowlist return 403 PAT_ROUTE_NOT_ALLOWED. This includes web research, billing, admin, and the PAT management endpoints themselves.

​
Tier requirements

Tier gating is enforced on every request the same way the web app enforces it. Roughly:
  • Solo / Scout, evaluation tiers, read-only access to your data via the agent API
  • Starter, the recommended baseline, full read + write
  • Growth and above, includes everything plus higher rate limits and feature additions
For current pricing and exact tier features, see the Audity pricing page. A 403 with requiredTier in the body tells you what to upgrade to.

​
Rate limits

Per-token, enforced by Audity’s existing rate limiter:
Endpoint classLimit
Standard reads60 / minute
Writes (create, update, delete)30 / minute
Expensive operations (audit synthesis)5 / minute
Capture submissions (POST /api/nucleus/capture/note)30 / hour
A 429 response includes Retry-After (in seconds). Back off and retry.

​
Rotation

We recommend rotating PATs every 90 days. Multiple active tokens make this zero-downtime:
  1. Create a new token with the same label suffixed -rotate (or with the new date)
  2. Update your agent’s connection settings to use the new token
  3. Verify with a GET /api/user/current round-trip
  4. Revoke the old token
Both tokens work in parallel until you revoke the old one. There’s no cutover window.

​
Revocation

To revoke a token: Settings → API Tokens → Revoke. The token stops working immediately on the next request (no caching). Revoke immediately if:
  • A token may have been exposed (committed to git, pasted into a chat, leaked to a screen recording)
  • A device is lost or stolen
  • An integration goes rogue or you stop trusting it
Revocation is a soft delete (revoked_at is set). The row stays in the database for audit history.

​
Security guidelines

Add .env, .env.local, *.env to your .gitignore. Use environment variables or a secret manager.
Tokens belong in connection settings, not message bodies. If you paste one accidentally, revoke it.
One token per device or integration. Easier to revoke a single compromised token without breaking everything else.
For tokens used in n8n, Zapier, or shared workflows, set a 30–90 day expiry. Forces rotation hygiene.
If your agent only fetches data (dashboards, reporting), give it a read token. Reduces blast radius.

​
Error codes

Authentication and validation errors return JSON with a stable code field. Branch on code (the human-readable error string may change). All error responses on /api/... routes are JSON, the middleware never returns HTML for an auth failure.

​
Authentication and authorization

HTTPcodeWhen it fires
401PAT_MALFORMEDThe Authorization header carries a Bearer aky_... token whose format is invalid (wrong length, wrong charset). Don’t retry, regenerate the token.
401(no code)A correctly-shaped aky_... token that doesn’t resolve to an active key. The token was revoked, expired, or never existed. Generate a new one.
403PAT_ROUTE_NOT_ALLOWEDValid PAT, but the route is not on the agent allowlist. Use a browser session for non-allowlisted routes.
403PAT_NOT_SUPPORTED_FOR_ENDPOINTValid PAT hitting a defense-in-depth Clerk-only endpoint (e.g. /api/user/api-keys). PATs cannot manage other PATs.
403PAT_SCOPE_INSUFFICIENTToken is valid but missing a scope. The error message lists what’s missing (e.g. Token missing required scope(s): write). Generate a token with the right scopes.
503PAT_DISABLEDThe agent API is gated behind a kill switch (AUDITY_AGENT_API_ENABLED). If you see this on prod, the switch is off, contact support.

​
Endpoint validation errors

HTTPcodeEndpoint
400EMPTY_PATCHPATCH /api/projects/{id} with no allowed fields
400INVALID_DESCRIPTION_TYPEPATCH /api/projects/{id} with a non-string description
400DESCRIPTION_TOO_LONGPATCH /api/projects/{id} with description over 5,000 chars

​
Out of scope for v1

A few capabilities are intentionally not exposed via the agent API:
  • Document upload. Files (PDFs, transcripts, contracts) are uploaded through the web app. Agents read them via project detail and trigger analysis on what’s already there.
  • Streaming responses. Audity is not a chatbot. Agents call the API for structured outputs, not for token-by-token completion. Stream prose with your own LLM; use Audity for synthesis, memory, and project state.
  • Deliverable document regeneration. The synthesis pipeline produces stakeholder memos and other deliverables when audit-analysis runs. Agents read them via GET /api/projects/{id}/deliverables.
  • Web research. The POST /api/projects/{id}/web-research route exists but is not on the agent allowlist in v1. It runs from the web app.
  • PAT management via PAT. Tokens are created and revoked from the browser. PATs cannot manage other PATs.
  • Listing ReadyLinks. The response shape is unstable behind a feature flag. Manage links via the web app; you can still filter the lead list by a known staticSlugId.
If you need any of these in your workflow, tell us.

​
What gets logged

Two systems run in parallel: The Nucleus action audit log (nucleus_actions table). Populated by the withAudit wrapper that sits around Nucleus’s internal AI tools and slash commands when you use Nucleus inside the web app. Records the user, tool, payload, and outcome for every Nucleus tool call. The agent API has its own surface and is not currently mirrored into nucleus_actions. PAT writes (create project, trigger audit, create memory, etc.) are persisted in their own tables (the rows themselves are the record), but there’s no per-call audit trail in v1. If you need an audit log for compliance reasons, run your agent-side requests through your own logging proxy until we ship a dedicated PAT activity feed.

​
What’s stored when you create a token

  • A bcrypt hash of the plaintext token
  • An HMAC lookup digest so the resolver can find the row without scanning every hash
  • The first 6 characters (e.g. aky_a1b) for visual identification in your settings
  • The label, scopes, expiry, created/last-used timestamps
When a request comes in, the middleware extracts the token, computes the lookup digest, fetches the row, verifies the bcrypt hash, updates last_used_at, and lets the request proceed with your normal Clerk identity attached.

​
Programmatic access

The PAT mechanism is designed for user-initiated, user-pasted integrations: a consultant pastes their token into Claude or n8n. Embedded SaaS-to-SaaS auth (where another product needs to issue and rotate tokens on a user’s behalf) is out of scope today. If you have a use case like that, reach out.

​
Need help?