Authentication
API keys, Bearer tokens, and capability mode for public job reads.
Mint an API key
Generate an API key from /settings?section=api-keys. Keys follow the format parcha-xyz-{32_hex} and are tied to your tenant. Treat them like passwords.
Open API keys →Bearer token
Send the key in the Authorization header on every request. Format: parcha-xyz-{32_hex}.
curl "https://api.grep.ai/api/v2/runs" \
-H "Authorization: Bearer parcha-xyz-1234567890abcdef..."Keep your API key secure
Never expose your API key in client-side code. Use server-side requests, environment variables, or a secrets manager.
OAuth2 for agents
Agent and delegated integrations can use Descope-issued OAuth access tokens minted for the Grep Public API v2 resource. API keys are still supported for direct server-to-server integrations.
curl "https://api.grep.ai/api/v2/runs" \
-H "Authorization: Bearer $OAUTH_ACCESS_TOKEN"Protected resource
https://api.grep.ai/api/v2Discovery
curl "https://api.grep.ai/.well-known/oauth-protected-resource/api/v2"
curl "https://api.grep.ai/.well-known/api-catalog"| Scope | Access |
|---|---|
research:read | Read runs, reports, files, timelines, quota, and usage. |
research:write | Start runs and manage run attachments. |
billing:read | Reserved for stricter billing reads as the billing surface grows. |
Sign in with AgentID
An AI agent with an AgentMail inbox can sign in to Grep as itself with AgentID: no human account and no API key. It proves a key it holds, approves the sign-in in its browser, and gets a short-lived token for Grep's MCP server.
Sign in an agent with AgentID →Capability mode (public jobs)
When a job is shared publicly, the job_id itself acts as a read capability. No Authorization header is needed for GET /api/v2/runs/{public_job_id}. This is what powers public share links — anyone with the URL can read, but nobody can mutate.
# Capability mode — public job, read-only access via the job_id itself.
curl "https://api.grep.ai/api/v2/runs/$PUBLIC_JOB_ID"
# No Authorization header required when the job is shared publicly.Read-only capability
Capability mode is read-only. POST/PATCH/DELETE always require an API key. Capability access is silently skipped if the job's visibility is private.
401 vs 403
Both indicate auth failure but mean different things — distinguishing them helps you write better retry logic.
| Status | Code | Meaning |
|---|---|---|
401 | unauthenticated | Your key is missing, malformed, or revoked. Don't retry without fixing the credential. |
403 | forbidden | Your key is valid but lacks permission for this resource. Often a tenant-mismatch — the job belongs to another tenant. |