# auth.md

You are an agent. RolesAPI supports agentic registration: discover, register, obtain user consent, exchange for an access_token, call the API, and handle revocation. Follow the steps in order.

RolesAPI is an independent REST API for Indeed job-postings data. The resource server is `https://api.rolesapi.com` and the authorization server is also `https://api.rolesapi.com`.

## Step 1: Discover

A 401 from the API carries a `WWW-Authenticate` header pointing at the Protected Resource Metadata:

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="rolesapi", resource_metadata="https://api.rolesapi.com/.well-known/oauth-protected-resource"
```

Fetch the Protected Resource Metadata (RFC 9728):

```http
GET https://api.rolesapi.com/.well-known/oauth-protected-resource
```

Then fetch the Authorization Server Metadata (RFC 8414), which includes the `agent_auth` block that points back to this document:

```http
GET https://api.rolesapi.com/.well-known/oauth-authorization-server
```

A mirror of both documents is published at `https://rolesapi.com/.well-known/oauth-protected-resource` and `https://rolesapi.com/.well-known/oauth-authorization-server`. The issuer is `https://api.rolesapi.com`.

## Step 2: Pick a method

RolesAPI supports one registration identity type:

- `anonymous`: register an OAuth client with no user identity, then bind it to a user account through the browser consent step below. No claim ceremony is required; consent happens inline during authorization.

Two credential types are issued:

- `oauth2_access_token`: obtained through the flow below. Grants the `mcp:access` scope for the MCP server at `https://api.rolesapi.com/mcp`.
- `api_key`: a long-lived key with the `rk_` prefix, created by a human at `https://rolesapi.com/signup` (100 free credits, no card). Sent as `Authorization: Bearer rk_...` for the REST API.

If you can open a browser for the user, use the OAuth flow. If you already hold an `rk_` key, skip to Step 6.

## Step 3: Register (anonymous, RFC 7591)

POST to the registration endpoint. No authentication or user identity is required. Public clients only; no secret is issued.

```http
POST https://api.rolesapi.com/oauth/register
Content-Type: application/json

{
  "client_name": "My Agent",
  "redirect_uris": ["https://example.com/callback"]
}
```

`redirect_uris` is required. Each URI must be `https` or `http://localhost`. The response is the stored client:

```json
{
  "client_id": "roc_...",
  "client_id_issued_at": 1751846400,
  "client_name": "My Agent",
  "redirect_uris": ["https://example.com/callback"],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "mcp:access"
}
```

Store the `client_id`. There is nothing secret in this response.

## Step 4: User consent (authorization code + PKCE)

Direct the user's browser to the authorization endpoint. PKCE with `S256` is required.

```
GET https://api.rolesapi.com/oauth/authorize
  ?response_type=code
  &client_id=roc_...
  &redirect_uri=https://example.com/callback
  &scope=mcp:access
  &state=<random>
  &code_challenge=<S256 challenge>
  &code_challenge_method=S256
```

The user signs in to their RolesAPI account and approves the client on a consent screen. This is the step that binds your anonymous registration to a user. The browser is redirected to your `redirect_uri` with `code` and `state`.

## Step 5: Exchange the code

```http
POST https://api.rolesapi.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=<code>
&redirect_uri=https://example.com/callback
&client_id=roc_...
&code_verifier=<verifier>
```

The response contains a bearer `access_token` scoped to `mcp:access`.

## Step 6: Use the credential

Send the token in the `Authorization` header (`bearer_methods_supported: ["header"]`):

- MCP server: `https://api.rolesapi.com/mcp` with `Authorization: Bearer <access_token>`
- REST API: `https://api.rolesapi.com/v1/...` with `Authorization: Bearer rk_...`

Machine-readable surfaces:

- OpenAPI 3.1: `https://rolesapi.com/openapi.json`
- Agent skills: `https://rolesapi.com/.well-known/agent-skills/index.json`
- Docs: `https://rolesapi.com/docs`

## Errors

Errors follow RFC 6749 shapes at the OAuth endpoints and a JSON `{ "error": { "code", "message" } }` envelope on the API. A 401 always includes the `WWW-Authenticate` discovery header from Step 1.

## Revocation

POST the token to the revocation endpoint (RFC 7009):

```http
POST https://api.rolesapi.com/oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<access_token>&client_id=roc_...
```

Users can also revoke access and API keys from the dashboard at `https://rolesapi.com/app/`. After revocation, requests return 401; re-run the flow from Step 4.