# Auth.md — authenticating agents with Jobably

Jobably is built for the account owner's OWN agent. There are two ways an
agent authenticates, and both end at the same record of what it did.

1. **OAuth 2.1 (chat apps and any OAuth-capable MCP client).** The agent
   discovers the flow on its own, sends the owner to Jobably to approve it,
   and receives short-lived tokens. Nothing is pasted.
2. **Personal access token (clients that send a fixed header).** The owner
   mints a token in the app and gives it to the agent.

## OAuth 2.1

| What | Where |
| --- | --- |
| Protected resource metadata (RFC 9728) | https://mcp.jobably.com/.well-known/oauth-protected-resource and https://api.jobably.com/.well-known/oauth-protected-resource |
| Authorization server metadata (RFC 8414) | https://api.jobably.com/.well-known/oauth-authorization-server |
| Authorization endpoint | https://api.jobably.com/oauth/authorize |
| Token endpoint | https://api.jobably.com/oauth/token |
| Dynamic client registration (RFC 7591) | https://api.jobably.com/oauth/register |
| Token revocation (RFC 7009) | https://api.jobably.com/oauth/revoke |

- **PKCE is required** (`code_challenge_method=S256`). The authorization
  code grant and the refresh token grant are supported.
- **Clients** register dynamically, or use a **Client ID Metadata Document**:
  an `https` URL as the `client_id` that serves a JSON document naming
  itself (`client_id` equal to the URL) and its `redirect_uris`. Such
  clients are shown to the owner with their verified domain.
- **Redirect URIs** must match exactly. `https` anywhere; `http` only on
  loopback (any port, per RFC 8252); private-use schemes for native apps.
- **Consent** happens in a signed-in Jobably session. The owner sees the
  agent's name, where they will be returned, and what it may do, and may
  narrow `read write` to `read`. A token can never approve another agent.
- **Tokens**: access tokens (`jbly_oat_…`) last one hour; refresh tokens
  (`jbly_ort_…`) last 30 days and rotate on every use. Presenting a rotated
  refresh token again revokes the whole connection, as does replaying an
  authorization code.
- **Resource indicators** (RFC 8707): `resource` may be
  `https://mcp.jobably.com/mcp` or `https://api.jobably.com`.
- An unauthenticated or expired request to the MCP server returns HTTP 401
  with `WWW-Authenticate: Bearer resource_metadata="…"`, which is how a
  client starts the flow.
- The owner disconnects an agent at any time in Settings → Connected agents;
  its tokens stop working on the next request.

## Personal access tokens

1. Sign in at https://app.jobably.com (Google, Microsoft, or email code).
2. Go to **Settings → Integrations → Personal access tokens**.
3. Create a token with the scopes your agent needs. The full token is shown
   exactly once; store it securely.

Tokens look like `jbly_pat_…`, are stored server-side only as hashes, and can
be revoked from the same screen at any time.

## Using a token

Send it as a bearer token on every request:

    Authorization: Bearer <token>

- **MCP**: https://mcp.jobably.com/mcp (Streamable HTTP; protocol versions
  2025-11-25, 2025-06-18 and 2025-03-26).
- **REST**: https://api.jobably.com — every route the MCP tools call.

## Scopes

| Scope    | Grants                                                                 |
| -------- | ---------------------------------------------------------------------- |
| `read`   | Matches, the short list, searches, the board, resumes and drafts, reports, lists, insights, the activity record, usage. |
| `write`  | Move jobs, record applications, run searches, tailor (spends plan credits), prep, lists, reports, profile and preferences. |
| `ingest` | Save postings captured from web pages (browser extension; tokens only). |

Session-only surfaces — sign-in, token management, approving agents, model
keys, billing and account deletion — are **never** available to a token or a
connected agent.

## The activity record

Every change to the account, from anyone, and every request made with a
token or by a connected agent, is recorded before it runs — with the agent's
name, the tool it used, what it acted on and the outcome. If the record
cannot be written, the change is not made. The owner reads it in Settings →
Activity; an agent reads it with the `get_activity` tool.

## Trust model

- Jobably never applies to a job. The owner applies; an agent records it.
- Tools that spend money (tailoring, prep packets) or change state require
  `confirm: true` — agents cannot spend silently. Tool annotations mark
  which tools only read.
- Tailored resumes are built only from the owner's own history: figures are
  never invented, whatever the agent asks for.
- One-off searches run for an agent are never scored against the owner's
  private rubric and are not saved.

Questions: https://jobably.com/contact