# Authentication

API keys, Bearer tokens, and capability mode for public job reads.

## Developer documentation
- [Developers](/developers.md)
- [api](/developers/api.md)
- [a2a](/developers/a2a.md)
- [api/v1](/developers/api/v1.md)
- [api/v2](/developers/api/v2.md)
- [api/quickstart](/developers/api/quickstart.md)
- [api/auth](/developers/api/auth.md)
- [api/idempotency](/developers/api/idempotency.md)
- [api/pagination](/developers/api/pagination.md)
- [api/webhooks](/developers/api/webhooks.md)
- [api/errors](/developers/api/errors.md)
- [mcp](/developers/mcp.md)
- [skills](/developers/skills.md)
- [sdks](/developers/sdks.md)
- [sdks/typescript/quickstart](/developers/sdks/typescript/quickstart.md)
- [sdks/typescript/reference](/developers/sdks/typescript/reference.md)
- [sdks/python/quickstart](/developers/sdks/python/quickstart.md)
- [sdks/python/reference](/developers/sdks/python/reference.md)
- [sdks/lifecycle](/developers/sdks/lifecycle.md)
- [sdks/skills](/developers/sdks/skills.md)
- [sdks/batches](/developers/sdks/batches.md)
- [sdks/loops](/developers/sdks/loops.md)
- [sdks/campaigns](/developers/sdks/campaigns.md)
- [sdks/results](/developers/sdks/results.md)
- [sdks/errors](/developers/sdks/errors.md)
- [api/agentid](/developers/api/agentid.md)

## Mint an API key

Generate an API key from /developers/keys. Keys follow the format parcha-xyz-{32_hex} and are tied to your tenant. Treat them like passwords.

## Bearer token

Send the key in the Authorization header on every request. Format: parcha-xyz-{32_hex}.

Keep your API key secure

Never expose your API key in client-side code. Use server-side requests, environment variables, or a secrets manager.

> [!WARNING] Keep your API key secure
> Never expose your API key in client-side code. Use server-side requests, environment variables, or a secrets manager.

```bash
curl "https://api.grep.ai/api/v2/research" \
  -H "Authorization: Bearer parcha-xyz-1234567890abcdef..."
```

## 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.

```bash
curl "https://api.grep.ai/api/v2/research" \
  -H "Authorization: Bearer $OAUTH_ACCESS_TOKEN"
```

```bash
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 research jobs, reports, files, timelines, quota, and usage. |
| research:write | Start research and manage research attachments. |
| billing:read | Reserved for stricter billing reads as the billing surface grows. |

## 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/research/{public_job_id}. This is what powers public share links — anyone with the URL can read, but nobody can mutate.

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.

> [!INFO] 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.

```bash
# Capability mode — public job, read-only access via the job_id itself.
curl "https://api.grep.ai/api/v2/research/$PUBLIC_JOB_ID"
# No Authorization header required when the job is shared publicly.
```

## 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. |

## Related

Full registry of error codes and the structured error envelope.

Browse every endpoint and schema in the auto-generated reference.