# auth.md

How an AI agent authenticates to Iridium. Iridium gives agents live access to LinkedIn, the
ability to act on it, and a record of everything they do. Every action runs as a specific human
user, so there is no anonymous access tier and no shared API key.

Machine-readable metadata is the source of truth. This page describes what those documents say.

## Who this is for

Agents and MCP clients connecting to the Iridium MCP server at
`https://api.iridiumhqmcp.com/mcp`. An MCP client that implements the standard OAuth flow needs
no configuration beyond that URL. It will discover everything below on its own.

## Discovery

The MCP endpoint answers an unauthenticated request with `401` and an RFC 9728 challenge:

```
WWW-Authenticate: Bearer resource_metadata="https://api.iridiumhqmcp.com/.well-known/oauth-protected-resource"
```

Follow that pointer to the Protected Resource Metadata, then the `authorization_servers` entry it
names to the Authorization Server Metadata:

| Document | URL |
| --- | --- |
| Protected Resource Metadata (RFC 9728) | `https://api.iridiumhqmcp.com/.well-known/oauth-protected-resource` |
| Authorization Server Metadata (RFC 8414) | `https://api.iridiumhqmcp.com/.well-known/oauth-authorization-server` |
| MCP Server Card | `https://iridiumhqmcp.com/.well-known/mcp/server-card.json` |
| OpenAPI 3.1 description | `https://api.iridiumhqmcp.com/openapi.json` |

The issuer is `https://api.iridiumhqmcp.com`. Note that the authorization endpoint sits on the
marketing origin, `https://iridiumhqmcp.com/oauth/authorize`, because that is where the human
sees the consent screen. That is what the metadata advertises, so follow the metadata rather
than assuming a single host.

## Registration

Iridium supports RFC 7591 dynamic client registration, so an agent that has never seen Iridium
before can register itself:

```
POST https://api.iridiumhqmcp.com/oauth/register
```

Registration is stateless. There is nothing to apply for, no key to request by email, and no
manual approval step.

## Getting a token

**Authorization code with PKCE.** This is the flow for an agent acting on behalf of a person.
PKCE is required and `S256` is the only accepted `code_challenge_method`; a request using `plain`
is rejected.

```
1. POST /oauth/register              (api.iridiumhqmcp.com)  -> client_id
2. GET  /oauth/authorize             (iridiumhqmcp.com)      -> the user signs in and consents
3. POST /oauth/token                 (api.iridiumhqmcp.com)  -> access token, scope "mcp"
```

Send the token as `Authorization: Bearer <token>`. Bearer tokens are accepted in the header only.

**Client credentials.** A second grant exists for directory indexers that read the public tool
catalogue on a schedule with no user present. It issues an introspection-only token
(`scope=mcp:introspect`) and cannot read or act on any LinkedIn account. Credentials for it are
issued by Iridium, not self-registered.

## What a token can do

A token carries one user. It reaches that user's LinkedIn connection and nothing else.

Read access is live. Profiles, posts, and messages are fetched at request time through the
connection the user authorized. There is no harvested profile database to read from.

Write access is gated in three ways, and none of them are things an agent can turn off:

- **Approval is a separate call.** Drafting and sending are different tools. An agent can draft
  a comment, a connection note, a reply, or a post. Only the approve call sends, and the product
  is built so a person makes that call.
- **Caps are enforced server side.** Daily and weekly limits on outreach and commenting are
  applied by Iridium, not by the agent's own restraint.
- **Everything is logged.** Every attempted action writes one row to an append-only ledger
  recording what ran, when, on whose behalf, whether it succeeded, and the exact text sent. An
  agent can read its own history back with `get_activity_log` and `get_last_action`, and the user
  can read it in the web app.

The tools available to a given token are filtered by what that account has enabled. Call
`list_tools` rather than assuming the full set.

## Revoking

The user can disconnect LinkedIn or delete the account from the Iridium web app, or by asking
their agent to call `disconnect_linkedin` or `delete_account`. Disconnecting ends the agent's
access to LinkedIn immediately while leaving the activity log readable.

## Contact

support@iridiumhqmcp.com. Operated by Progress Labs LLC (dba Iridium).