# RolePark: authentication for AI agents

> RolePark is an applicant tracking and HR system. AI agents reach it through one remote MCP server and always act for a signed-in person: they see and change exactly what that person can. There is no anonymous or agent-only access and no API key for agents.

- MCP server (Streamable HTTP, JSON responses, no sessions): https://rolepark.com/api/mcp
- Documentation for people: https://rolepark.com/ai-assistants
- MCP Server Card: https://rolepark.com/.well-known/mcp/server-card.json
- API catalog (`application/linkset+json`): https://rolepark.com/.well-known/api-catalog

## 1. Discover

Call the MCP server without a token. It answers `401` with `WWW-Authenticate: Bearer resource_metadata="https://rolepark.com/.well-known/oauth-protected-resource/api/mcp"`.

- Protected resource metadata for the MCP server (RFC 9728): https://rolepark.com/.well-known/oauth-protected-resource/api/mcp
- Protected resource metadata for the site: https://rolepark.com/.well-known/oauth-protected-resource
- Authorization server metadata (RFC 8414): https://rolepark.com/.well-known/oauth-authorization-server

## 2. Register the client

Both options are advertised in the authorization server metadata.

- **Client ID Metadata Document** (`client_id_metadata_document_supported: true`): use the HTTPS URL of your client metadata document as `client_id`. The `client_id` inside the document must equal its URL, redirect URIs must be on the same origin as the document or on loopback, and shared secrets are not accepted: use `token_endpoint_auth_method: none`.
- **Dynamic Client Registration** (RFC 7591): `POST https://rolepark.com/api/oauth/register`. Redirect URIs: any `https` URL, or `http` only on `localhost`, `127.0.0.1` or `[::1]`; no custom schemes and no fragments.

## 3. Authorize (authorization code with PKCE)

Send the person to `https://rolepark.com/oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `state`, `code_challenge` with `code_challenge_method=S256` (the only method), `scope` and `resource=https://rolepark.com/api/mcp` (RFC 8707).

- `rolepark.read`: view candidates, vacancies, hiring pipelines, matching, own interviews and tasks. Always granted.
- `rolepark.write`: create, edit, publish and close vacancies, add and edit candidates, put them into vacancies, move pipeline stages, schedule interviews, email candidates, add notes and tasks. Optional: the person chooses it on the consent screen. It authorises the calls; RolePark runs an allowed call at once and does not ask the person again for each action.

The person signs in to RolePark with a company account and approves on the consent screen. The redirect carries `code`, `state` and `iss` (RFC 9207).

**Company access.** In a company that signed up for RolePark by itself, AI agents are on from the start with View and changes; in other companies a company administrator turns them on. An administrator can switch them off or choose View only or View and changes in Company settings → AI agents; with View only, `rolepark.write` is never granted. Candidate accounts cannot connect agents.

## 4. Get and refresh tokens

`POST https://rolepark.com/api/oauth/token` with `grant_type=authorization_code`, `code`, `redirect_uri`, `code_verifier` and `client_id`. Access tokens are opaque bearer tokens valid for 1 hour. Refresh tokens are valid for 30 days and rotate on every use; reusing an old one more than 60 seconds after it was exchanged revokes the whole connection.

## 5. Call the MCP server

`POST` JSON-RPC to https://rolepark.com/api/mcp with `Authorization: Bearer <token>` (header only). `GET` and `DELETE` return `405`: there are no sessions or event streams. Up to 10 messages per batch; 120 calls per minute per person and 600 per company, then `429` with `Retry-After`. The tool set depends on the granted scopes: read it from `tools/list`. Requests from web pages on other origins are refused.

## 6. Revocation

- Client: `POST https://rolepark.com/api/oauth/revoke` (RFC 7009).
- Person: Profile → AI agents → Disconnect. A company administrator can disconnect any connection of the company there, or turn AI agents off for everyone. A deactivated user's connections stop working.
- After revocation the MCP server answers `401` with `error="invalid_token"`: start again at step 3.

## Contact

help@rolepark.com