# itjobs.pt auth.md

How AI agents, integrations and partners get access to itjobs.pt (ITJobs - technology jobs, companies, courses and events).

## Audience

- **AI assistants acting for a candidate** (Claude, ChatGPT and other MCP clients): use the MCP server - the candidate signs in to their itjobs.pt account and authorizes the assistant (OAuth 2.1).
- **Partners and integrations** (ATSs, job aggregators, company websites) that list, search, publish or edit jobs: use the REST API with an API key.

## MCP server (candidate account, OAuth 2.1)

- Endpoint: `https://www.itjobs.pt/mcp` - Streamable HTTP, `POST`, JSON-RPC 2.0 (MCP protocol `2025-06-18`, also `2025-03-26` and `2024-11-05`)
- Health check: `GET https://www.itjobs.pt/mcp/health`
- Setup and tools: `https://www.itjobs.pt/mcp`
- Every request needs `Authorization: Bearer <access token>`. Without one the server answers `401` with `WWW-Authenticate: Bearer resource_metadata="https://www.itjobs.pt/.well-known/oauth-protected-resource/mcp"` - MCP clients follow it and start the sign-in on their own.
- Candidate accounts only (company accounts use the REST API).

### OAuth 2.1 authorization server

- Discovery: `https://www.itjobs.pt/.well-known/oauth-authorization-server` (RFC 8414) and `https://www.itjobs.pt/.well-known/oauth-protected-resource/mcp` (RFC 9728)
- Client registration: dynamic, `POST https://www.itjobs.pt/oauth/register` (RFC 7591) - public clients (`token_endpoint_auth_method: none`) or with a secret (`client_secret_post` / `client_secret_basic`). Redirect URIs: `https`, `http` on loopback only, or an app's own scheme.
- Authorization: `https://www.itjobs.pt/oauth/authorize` - authorization code with PKCE (`S256`, required); the candidate signs in and approves on a consent screen. The response includes `iss` (RFC 9207).
- Tokens: `POST https://www.itjobs.pt/oauth/token` - `authorization_code` and `refresh_token`. Access tokens last 1 hour; refresh tokens 90 days and rotate on every use (a refresh token used twice revokes the connection).
- Revocation: `POST https://www.itjobs.pt/oauth/revoke` (RFC 7009). Candidates can also disconnect apps in their profile, and changing the password disconnects all of them.
- Resource: tokens are issued for `https://www.itjobs.pt/mcp` (RFC 8707 `resource`) and only work there.
- Scopes: `jobs:read`, `profile:read`, `cv:read`, `applications:read`, `applications:write`. With no `scope` requested, all of them are granted.

## REST API (API key)

- Base URL: `https://api.itjobs.pt` (e.g. `https://api.itjobs.pt/job/search.json`)
- Documentation: `https://www.itjobs.pt/api/docs`
- Credential: an API key, sent as the `api_key` parameter (query string or form body) on every request:

```
curl --data "api_key=YOUR_KEY&q=java&limit=5" https://api.itjobs.pt/job/search.json
```

### Getting an API key (registration)

There is no automatic agent registration endpoint. Keys are provisioned by humans:

1. A company account creates and manages its keys in its backoffice: `https://www.itjobs.pt/admin/api` (create, enable, disable, delete). Company accounts are free: `https://www.itjobs.pt/planos`.
2. Partners without a company account: contact ITJobs through `https://www.itjobs.pt` to request a key.

A key created by a company acts for that company: jobs published with it belong to it and go through the usual moderation and plan limits.

### Using and protecting the key

- Keep the key secret (server-side only); anyone with it can act for that company.
- A disabled or deleted key stops working immediately - rotate it from `https://www.itjobs.pt/admin/api` if it leaks.

## Not supported

- OAuth for the REST API (it uses API keys) or for company accounts.
- Client ID Metadata Documents (CIMD) - MCP clients register dynamically instead.
- OpenID Connect ("log in with itjobs.pt").