# API Authentication - Grep

[Developers](/developers)[API Reference](/developers/api)Authentication

# Authentication

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

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

[Open API keys →](/developers/keys)

## Bearer token

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

curl

```
curl "https://api.grep.ai/api/v2/research" \
  -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

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

### Protected resource

`https://api.grep.ai/api/v2`

### Discovery

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.

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

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

## Related

### [Error codes](/developers/api/errors)

[Full registry of error codes and the structured error envelope.](/developers/api/errors)

### [API v2 reference](/developers/api/v2)

[Browse every endpoint and schema in the auto-generated reference.](/developers/api/v2)