# Sign in and API keys for MCP

> How MCP clients authenticate with GreenHired: OAuth 2.1 with PKCE and dynamic registration, the token lifetimes, the permissions, and API-key mode.

- Source: https://greenhired.com/developers/mcp/authentication/
- Section: GreenHired developers · MCP server · Start here
- Last updated: 2026-11-21

## Two ways to authenticate

Send a bearer token in `Authorization`. If you send none, the server answers `401` with a `WWW-Authenticate` header that tells an MCP client how to sign in, so most clients handle it for you.

|  | Sign in with GreenHired | API key |
| --- | --- | --- |
| Header | `Authorization: Bearer ghat_...` | `Authorization: Bearer ghk_...` |
| Who it represents | A person: a job seeker or an employer | An app or partner |
| Tools | [Account tools](https://greenhired.com/developers/mcp/tools/) the person allowed, plus the three job search tools | `search_jobs`, `get_job`, `list_categories` |
| Limits | Counted per connection (120 requests and 30 changes a minute) | Counted on the key. See [Rate limits](https://greenhired.com/developers/api/v1/limits/) |

## The sign-in flow (OAuth 2.1)

GreenHired follows the MCP authorization flow. Every step is standard, so a compliant client needs no GreenHired-specific code.

1. The client sends `POST https://mcp.greenhired.com/mcp` with no credential and gets `401` plus `WWW-Authenticate` pointing at the protected-resource metadata.
2. It reads `https://mcp.greenhired.com/.well-known/oauth-protected-resource` (RFC 9728). The authorization server is `https://greenhired.com`.
3. It reads `https://greenhired.com/.well-known/oauth-authorization-server` (RFC 8414) for the endpoints.
4. It registers itself: `POST https://mcp.greenhired.com/oauth/register` with JSON (dynamic client registration, RFC 7591). It gets a `client_id` and no secret.
5. It sends the person to `https://greenhired.com/oauth/authorize/` with a PKCE challenge (S256). The person signs in and ticks permissions.
6. GreenHired redirects back with a one-time `code` (valid for 60 seconds) and `iss`.
7. The client exchanges it at `POST https://mcp.greenhired.com/oauth/token` for an access token and a refresh token.
8. It calls `https://mcp.greenhired.com/mcp` with `Authorization: Bearer ghat_...`.

| Endpoint | Address |
| --- | --- |
| Protected-resource metadata | `https://mcp.greenhired.com/.well-known/oauth-protected-resource` |
| Authorization-server metadata | `https://greenhired.com/.well-known/oauth-authorization-server` |
| Authorization | `https://greenhired.com/oauth/authorize/` |
| Registration | `https://mcp.greenhired.com/oauth/register` |
| Token | `https://mcp.greenhired.com/oauth/token` |
| Revocation | `https://mcp.greenhired.com/oauth/revoke` |

> **Info:** The token, registration and revocation endpoints are on the MCP host because apps send them as form posts, which the website refuses without a matching `Origin`. The MCP host turns them into JSON for the website.

## Rules for apps

- Public clients only: there is no client secret. PKCE with `S256` is required.
- Redirect addresses are strict: `https` with a real host name; `http` only for `127.0.0.1`, `[::1]` and `localhost`; or a private-use scheme for a native app such as `cursor://`. At most 5 per app, matched exactly (a loopback address may differ in its port).
- An app name may not contain "GreenHired".
- A code works once, within 60 seconds. Using it twice revokes what was made from it.
- An access token lasts 60 minutes. A refresh token lasts 30 days and works **once**: a refresh gives a new pair, and reusing an old refresh token revokes the whole family. After 180 days from the person's yes, the app must ask again.
- A person can have 20 apps connected at once.

## Permissions (scopes)

| Permission | For | Tools it opens |
| --- | --- | --- |
| `profile:read` | Job seekers | `get_my_profile` |
| `profile:write` | Job seekers | `update_my_profile` |
| `applications:read` | Job seekers | `list_my_applications` |
| `saved:read` | Job seekers | `list_my_saved_jobs` |
| `saved:write` | Job seekers | `save_job`, `unsave_job` |
| `company:read` | Employers | `get_my_company` |
| `jobs:read` | Employers | `list_company_jobs` |

`get_my_account` needs any valid connection. A write permission needs its read permission. An app that asks for a permission outside this list, such as `jobs:write`, is refused with `invalid_scope`: job changes are not available to assistants.

## API-key mode

For a program that is not acting for a person, ask for an API key (see [Authentication for the API](https://greenhired.com/developers/api/v1/authentication/)) with `jobs:read` and `categories:read`, and send it as a bearer token. Every tool call is then one call to the public jobs API with your key, so the key's permissions, limits and source rules are the API's.

```bash
curl -s https://mcp.greenhired.com/mcp \
  -H "Authorization: Bearer $GREENHIRED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_jobs","arguments":{"category":["renewable-energy"],"work_mode":["remote"],"limit":5}}}'
```

## Frequently asked questions

**Do I have to implement OAuth myself?**

Not if you use an MCP client such as Claude, ChatGPT, Cursor or Claude Code: they handle discovery, registration, PKCE and refresh. Implement the flow yourself only if you are writing a client.

**Why was my refresh token rejected?**

A refresh token works once. If a refresh succeeds on our side but the answer is lost, the retry looks like a reused token and the whole family is revoked. The person has to connect the app again.

**Can I get a client secret?**

No. GreenHired accepts public clients only, protected by PKCE.

**How does a person see and remove connected apps?**

On the Connected apps page of their account. An employer's company owners can also see and remove their members' connections.

## Related pages

- https://greenhired.com/developers/mcp/quickstart/
- https://greenhired.com/developers/mcp/security/
- https://greenhired.com/developers/api/v1/authentication/
