MCP server · Start here

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.

3 min read Updated Maintained by the GreenHired team
View Markdown
On this page
  1. Two ways to authenticate
  2. The sign-in flow (OAuth 2.1)
  3. Rules for apps
  4. Permissions (scopes)
  5. API-key mode
  6. Frequently asked questions

#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.

ItemSign in with GreenHiredAPI key
HeaderAuthorization: Bearer ghat_...Authorization: Bearer ghk_...
Who it representsA person: a job seeker or an employerAn app or partner
ToolsAccount tools the person allowed, plus the three job search toolssearch_jobs, get_job, list_categories
LimitsCounted 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.

  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_....
EndpointAddress
Protected-resource metadatahttps://mcp.greenhired.com/.well-known/oauth-protected-resource
Authorization-server metadatahttps://greenhired.com/.well-known/oauth-authorization-server
Authorizationhttps://greenhired.com/oauth/authorize/
Registrationhttps://mcp.greenhired.com/oauth/register
Tokenhttps://mcp.greenhired.com/oauth/token
Revocationhttps://mcp.greenhired.com/oauth/revoke

#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)

PermissionForTools it opens
profile:readJob seekersget_my_profile
profile:writeJob seekersupdate_my_profile
applications:readJob seekerslist_my_applications
saved:readJob seekerslist_my_saved_jobs
saved:writeJob seekerssave_job, unsave_job
company:readEmployersget_my_company
jobs:readEmployerslist_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
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.