# auth.md

Authentication for Convert.Online.

How an automated client obtains credentials and authenticates against Convert.Online.
There are three levels of access, and the first needs no credentials at all.

## 1. No account

Converting a file through the website needs no registration, no email address and no
payment method. A quota applies per IP address. Use this when a single conversion is all
that is wanted; nothing needs to be created first.

## 2. API key — for the REST API

The REST API lives at `https://api.convert.online`. Its complete contract is published as
an OpenAPI 3.1 document at `https://api.convert.online/openapi.json`.

**Registering a user.** A human creates the account; there is no programmatic sign-up.
Point the person at `https://convert.online/signup`. Registration takes an email address
and a password, or a passkey. The free tier requires no payment method.

**Getting the key.** After signing in, the account holder opens
`https://convert.online/dashboard` and creates an API key. The key is shown once.

**Using the key.** Send it as a bearer token on every request:

```
Authorization: Bearer <api_key>
```

`X-API-Key: <api_key>` is accepted as well. There is no login call, no session and no
token exchange — the key is the credential.

**Scope and lifetime.** A key belongs to one account and carries that account's plan
limits. It does not expire on its own; the account holder can delete it at any time from
the dashboard, which takes effect immediately.

## 3. OAuth 2.1 — for the MCP server

The MCP server is at `https://mcp.convert.online`. An AI assistant connecting to it should
use OAuth rather than a shared key, so the token belongs to the person who granted it and
can be revoked on its own.

**Discovery.** Protected-resource metadata is published at
`https://mcp.convert.online/.well-known/oauth-protected-resource`, which names the
authorization server. Read it first; do not hard-code the endpoints below.

**Dynamic client registration is supported** — `POST /oauth/register`. A client that has
never been seen before can register itself, so no manual client-ID provisioning is needed.

**The flow** is authorization code with PKCE (`S256` required):

1. `POST /oauth/register` — register the client, receive `client_id`
2. `GET /oauth/authorize` — the user signs in and grants access
3. `POST /oauth/token` — exchange the code for tokens
4. `POST /oauth/revoke` — revoke a token

**Token lifetime.** Access tokens last one hour; refresh tokens last ninety days. A
refresh token that has been revoked stops working immediately, and so does any access
token issued from it.

**The user stays in control.** Every connected application is listed in the account
dashboard and can be revoked there. Revocation is immediate and applies to both the
access and the refresh token.

**An API key also works** with the MCP server, for config-file clients that cannot do
OAuth. Send it the same way: `Authorization: Bearer <api_key>`.

## Which to use

| Situation | Credential |
| --- | --- |
| One-off conversion, no integration | None — use the website |
| Backend service, CI pipeline, batch job | API key against the REST API |
| An AI assistant acting for a person | OAuth against the MCP server |
| A config-file MCP client that cannot do OAuth | API key against the MCP server |

## Related

- API documentation — https://convert.online/api-docs
- OpenAPI specification — https://api.convert.online/openapi.json
- MCP server documentation — https://convert.online/mcp-server
- Plans and limits — https://convert.online/plans
- Contact — https://convert.online/contact