# Companies Daily auth.md

> Company pages, daily editions, SEC filing events and the REST API are public: the REST API and the MCP server work without registration and without a token. Sign-in (OAuth 2.1) is needed only for the list of companies a particular reader follows.

## Who this is for

AI agents and MCP clients acting for a particular reader of Companies Daily (companiesdaily.com) who wants the agent to show the companies they follow, add a company to the list or remove one. When each edition closes, the reader gets one email with the new SEC filings of the followed companies. For the data alone, do not register: call the public tools without an `Authorization` header.

## What needs a token

The MCP server <https://companiesdaily.com/mcp>:

| Tool | Scope | What it does |
|---|---|---|
| `list_followed_companies` | `watchlist:read` | the reader's followed companies (name, CIK, tickers, status, last filing in an edition, url of the company page) and whether email alerts are on |
| `follow_company` (`cik` or `ticker`) | `watchlist:write` | adds a company from the Companies Daily database to the list (at most 50 per account) |
| `unfollow_company` (`cik` or `ticker`) | `watchlist:write` | removes a company from the list |

Calling these tools without a token gives `HTTP 401` with the header `WWW-Authenticate: Bearer resource_metadata="https://companiesdaily.com/.well-known/oauth-protected-resource/mcp", scope="watchlist:read watchlist:write"`. A token with too narrow a scope: `HTTP 403`, `error="insufficient_scope"`. The reader's account is their email address confirmed by signing in; if there is none, it is created with the first company added. The REST API (<https://companiesdaily.com/wp-json/cd/v1>) has no account endpoints and takes no tokens.

## Discovery

1. Protected resource metadata (RFC 9728): <https://companiesdaily.com/.well-known/oauth-protected-resource/mcp> (resource <https://companiesdaily.com/mcp>) or <https://companiesdaily.com/.well-known/oauth-protected-resource> (the whole site).
2. Authorization server metadata (RFC 8414): <https://companiesdaily.com/.well-known/oauth-authorization-server> – issuer <https://companiesdaily.com>, block `agent_auth`, JWKS <https://companiesdaily.com/oauth/jwks.json>.

## Registration

Two methods. Both end the same way: an access token for <https://companiesdaily.com/mcp> after the reader signs in with a link from an email and gives consent. There are no passwords and no API keys.

### 1. OAuth 2.1 with dynamic client registration (MCP clients)

1. `POST` <https://companiesdaily.com/oauth/register> (RFC 7591, JSON): `redirect_uris` (https, or <http://127.0.0.1>/`localhost`/`[::1]` for native apps; the loopback port may change), `client_name`, `token_endpoint_auth_method` (`none` for public clients, or `client_secret_basic`/`client_secret_post`), `grant_types: ["authorization_code","refresh_token"]`. Answer `201` with `client_id` (and `client_secret` for a confidential client).
2. Browser: `GET` <https://companiesdaily.com/oauth/authorize?response_type=code&client_id=…&redirect_uri=…&scope=watchlist:read%20watchlist:write&state=…&code_challenge=…&code_challenge_method=S256&resource=https://companiesdaily.com/mcp> – PKCE S256 is required, `redirect_uri` exactly as registered.
3. The reader enters an email address, clicks the link (or types the 6-digit code) and sees on the consent screen the name of the client, the return address, the scopes and the resource.
4. Return: `redirect_uri?code=…&state=…&iss=` <https://companiesdaily.com> (check `state` and `iss`). The code works for 3 minutes, once.
5. `POST` <https://companiesdaily.com/oauth/token> (`application/x-www-form-urlencoded`): `grant_type=authorization_code&code=…&redirect_uri=…&code_verifier=…&client_id=…&resource=` <https://companiesdaily.com/mcp>.

### 2. Agent registration (auth.md, `service_auth`)

When the agent knows only the reader's email address and has no browser with a redirect:

1. `POST` <https://companiesdaily.com/oauth/agent/identity> (JSON) `{"type":"service_auth","login_hint":"reader@example.com","client_name":"Agent name"}`. The shape `{"type":"identity_assertion","assertion_type":"verified_email","assertion":"reader@example.com"}` is accepted too – the address is still confirmed by a sign-in link. Answer `200`: `registration_id`, `claim_token` (returned once), `claim_token_expires` (1 h), `post_claim_scopes`, `claim` = `user_code` (6 digits), `verification_uri`, `expires_in` (600), `interval` (5).
2. Show the reader `verification_uri` and `user_code` in one message. The reader opens the link, signs in with the link we email to that address, checks what you ask for and types `user_code` on our page.
3. Poll `POST` <https://companiesdaily.com/oauth/token> with `grant_type=urn:workos:agent-auth:grant-type:claim&claim_token=…` at most every `interval` seconds. Answers: `authorization_pending`, `slow_down`, `expired_token` (a new code: `POST` <https://companiesdaily.com/oauth/agent/identity/claim> with `{"claim_token":"…","email":"…"}`), `access_denied` (the reader declined), and after consent the usual token response with `access_token`, `refresh_token`, `scope` and `client_id`.

## Credentials

- `Authorization: Bearer <access_token>` in every request to <https://companiesdaily.com/mcp>. Never in the URL.
- Access token: JWT RS256 (`typ: at+jwt`), valid 3600 s, `aud` = the resource you asked for (`resource`). It does not work on another resource.
- Refresh: `grant_type=refresh_token&refresh_token=…` (+ `client_id`/client secret). Every use gives a new refresh token; reusing an old one revokes the whole chain. A refresh token lives 30 days from its last use, a chain at most 90 days.
- On `HTTP 401` with `error="invalid_token"` refresh the token once; on `invalid_grant` start again from registration.

## Revocation

- Agent: `POST` <https://companiesdaily.com/oauth/revoke> (RFC 7009) `token=…&token_type_hint=refresh_token` – revoking a refresh token ends its whole chain. Always `200`.
- Reader: the account page https://companiesdaily.com/account/ (after signing in) or "Your connected apps" https://companiesdaily.com/oauth/apps/ (the link also comes by email after every new connection). Revocation works at once, also for access tokens already issued.

## Limits

MCP server and REST: 60 requests per minute per IP (`429`, `Retry-After`). Client registrations: 10 per hour per IP. Sign-in emails: 3 per 15 minutes per address. Token endpoint: 60 requests per minute per IP. Code from the email and `user_code`: 5 attempts. Followed companies: at most 50 per account, 100 changes to the list per day.

## Data and privacy

We store the reader's email address, the list of followed companies (CIKs and dates), the name of the client, the scopes and the dates of consent. Tokens, codes and links only as HMAC hashes. A security log without email addresses or IP addresses in readable form, 90 days. Details: https://companiesdaily.com/privacy-policy/ (sections on followed companies and connected apps). Documentation: https://companiesdaily.com/for-agents/. Contact: newsroom@companiesdaily.com.
