# JobsPipe API authentication & agent auth (auth.md)

> How AI agents authenticate to the JobsPipe API. Developer resources hub: https://jobspipe.dev/developers

JobsPipe authenticates agents and machine clients with **API keys** (Bearer tokens). This is the supported, secure method for programmatic access. There is no dynamic client registration; OAuth social login (Google/GitHub) exists only for human sign-in to the dashboard.

## Audience

Autonomous AI agents and MCP clients that need programmatic, authenticated access to the JobsPipe Jobs API and tools.

## Pick a method

JobsPipe supports one credential type for agents:

- **API key** - a Bearer token prefixed `jp_live_`, issued from the dashboard. Free tier: 5,000 requests/month, no card. Get one at https://jobspipe.dev/signup.

Human users can also sign in to the dashboard with Google or GitHub, but those flows are for the web app, not for agent API access.

## Discover

Machine-readable metadata for the API (the protected resource):

- Protected-resource metadata (RFC 9728): https://api.jobspipe.dev/.well-known/oauth-protected-resource
- Authorization-server metadata (RFC 8414): https://api.jobspipe.dev/.well-known/oauth-authorization-server
- JWKS: https://api.jobspipe.dev/api/auth/jwks
- OpenAPI spec: https://jobspipe.dev/openapi.json
- API catalog (RFC 9727): https://jobspipe.dev/.well-known/api-catalog

An unauthenticated request to a protected endpoint returns `401` with a `WWW-Authenticate: Bearer resource_metadata="https://api.jobspipe.dev/.well-known/oauth-protected-resource"` header, so an agent can discover this document from a single request.

## Register

The authorization-server metadata carries an `agent_auth` block (WorkOS auth.md convention) describing programmatic registration endpoints:

- `register_uri`: https://api.jobspipe.dev/agent/auth
- `claim_uri`: https://api.jobspipe.dev/agent/auth/claim
- `revocation_uri`: https://api.jobspipe.dev/agent/auth/revoke
- `identity_types_supported`: `identity_assertion` - assertion types `urn:ietf:params:oauth:token-type:id-jag` and `verified_email`, credential type `api_key`.

To begin registration, POST to the register endpoint:

```http
POST https://api.jobspipe.dev/agent/auth
Content-Type: application/json

{ "identity_type": "identity_assertion" }
```

JobsPipe issues API keys per account rather than minting anonymous credentials, so the response directs you to https://jobspipe.dev/signup to create or bind a key. Once you hold a key, use it as the Bearer credential below.

## Use the credential

Send the API key as a Bearer token. Base URL: https://api.jobspipe.dev.

```
Authorization: Bearer jp_live_YOUR_KEY
```

```
curl -s https://api.jobspipe.dev/v1/jobs/search \
  -H "Authorization: Bearer jp_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_title_or":["software engineer"],"limit":5}'
```

The live endpoints are described by the OpenAPI spec at https://jobspipe.dev/openapi.json.

## Rate limits

Responses carry RFC RateLimit headers (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`). On `429`, a `Retry-After` header tells you when to retry.

## Errors

- `401` - missing or invalid API key. The `WWW-Authenticate` header points at the protected-resource metadata.
- `402` - monthly request quota exceeded for your plan.
- `429` - per-second rate limit exceeded; back off and retry after `Retry-After`.
- `502` - tech-stack scanner failed; retry or request `mode: "render"`.
- `504` - upstream timed out; retry.

## Revocation

Revoke or rotate an API key from the dashboard at https://jobspipe.dev/dashboard/api. Revoked keys stop working immediately.