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.
On this page
#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.
| Item | 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 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 |
#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.
- The client sends
POST https://mcp.greenhired.com/mcpwith no credential and gets401plusWWW-Authenticatepointing at the protected-resource metadata. - It reads
https://mcp.greenhired.com/.well-known/oauth-protected-resource(RFC 9728). The authorization server ishttps://greenhired.com. - It reads
https://greenhired.com/.well-known/oauth-authorization-server(RFC 8414) for the endpoints. - It registers itself:
POST https://mcp.greenhired.com/oauth/registerwith JSON (dynamic client registration, RFC 7591). It gets aclient_idand no secret. - It sends the person to
https://greenhired.com/oauth/authorize/with a PKCE challenge (S256). The person signs in and ticks permissions. - GreenHired redirects back with a one-time
code(valid for 60 seconds) andiss. - The client exchanges it at
POST https://mcp.greenhired.com/oauth/tokenfor an access token and a refresh token. - It calls
https://mcp.greenhired.com/mcpwithAuthorization: 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 |
#Rules for apps
- Public clients only: there is no client secret. PKCE with
S256is required. - Redirect addresses are strict:
httpswith a real host name;httponly for127.0.0.1,[::1]andlocalhost; or a private-use scheme for a native app such ascursor://. 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) 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.
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.
Was this page helpful?