# auth.md

You are an agent. This document tells you how to authenticate to **Jutusta**
(https://www.jutusta.ee) so you can call its speech API — text-to-speech, voice cloning,
transcription, summaries, translation and noise removal. Follow the path that
matches what you have; do not skip ahead.

Jutusta is a standard **OAuth 2.1 / OIDC authorization server**. There are two
ways to get a bearer credential:

1. **Act on a user's behalf (OAuth 2.1).** Register as a client, then run the
   authorization-code + PKCE flow. The user signs in and consents; you receive
   an access token scoped to their account. This is the right path for an agent
   platform serving many users.
2. **Act as a single developer (API key).** A human signs in to Jutusta and
   mints an opaque API key (`sk_jt_…`) from the dashboard. Simplest path for
   your own bot. No OAuth dance.

Both credentials are presented the same way at call time (Step 4).

## Step 1 — Discover

Two machine-readable documents describe everything below. Fetch them first:

- **Protected Resource Metadata** (RFC 9728):
  `https://www.jutusta.ee/.well-known/oauth-protected-resource`
  Tells you the API `resource`, the `authorization_servers`, the
  `scopes_supported`, and that bearer tokens go in the `Authorization` header.
  A 401 from `https://www.jutusta.ee/api/v1/*` also points here via its
  `WWW-Authenticate: Bearer … resource_metadata="…"` header.
- **Authorization Server Metadata** (RFC 8414):
  `https://www.jutusta.ee/.well-known/oauth-authorization-server`
  Carries the standard `authorization_endpoint` / `token_endpoint` /
  `registration_endpoint` plus an `agent_auth` block summarizing this file.

Prefer the values you read from those documents over the literals below.

## Step 2 — Pick a method

- You want to act on **a Jutusta user's behalf** → OAuth 2.1 (Step 3a). The user
  is in the loop: they sign in and approve the scopes on a consent screen.
- You are wiring up **your own** integration and can have a human sign in once →
  API key (Step 3b).

Jutusta does **not** support anonymous registration, ID-JAG identity
assertions, or an email "claim ceremony". If your platform expects one of those,
fall back to the OAuth flow (a human consents) or an API key.

## Step 3a — OAuth 2.1 (act on a user's behalf)

1. **Register a client** (RFC 7591 Dynamic Client Registration). POST your
   client metadata (`redirect_uris`, `client_name`, etc.) to:
   ```http
   POST https://www.jutusta.ee/api/auth/mcp/register
   Content-Type: application/json

   { "redirect_uris": ["https://your-agent.example/callback"], "client_name": "Your Agent" }
   ```
   You get back a `client_id` (and a `client_secret` unless you registered as
   a public `none`-auth client using PKCE).
2. **Authorize.** Send the user to the authorization endpoint with PKCE:
   ```
   https://www.jutusta.ee/api/auth/mcp/authorize?response_type=code&client_id=<id>&redirect_uri=<uri>
     &scope=openid%20profile%20email%20offline_access%20tts%20asr%20voices%20summary%20translate%20denoise&code_challenge=<S256>&code_challenge_method=S256&state=<state>
   ```
   The user signs in to Jutusta and approves the requested scopes on the consent
   screen. On approval you receive `code` at your `redirect_uri`.
3. **Exchange the code** for an access token:
   ```http
   POST https://www.jutusta.ee/api/auth/mcp/token
   Content-Type: application/x-www-form-urlencoded

   grant_type=authorization_code&code=<code>&redirect_uri=<uri>&client_id=<id>&code_verifier=<verifier>
   ```
   The response is a standard OAuth token response (`access_token`,
   `token_type: "Bearer"`, `expires_in`, `scope`, and a `refresh_token` when
   `offline_access` was granted). Use `refresh_token` to mint fresh access
   tokens without sending the user back through consent.

## Step 3b — API key (act as a single developer)

A signed-in user creates and revokes API keys at `https://www.jutusta.ee/app/developers`.
Keys are prefixed `sk_jt_`. There is no programmatic minting — this path
assumes a human holds the account.

## Step 4 — Use the credential

Both an OAuth access token and an API key are presented as a bearer credential:

```http
POST https://www.jutusta.ee/api/v1/text-to-speech/kerli
Authorization: Bearer <oauth-access-token | sk_jt_…>
Content-Type: application/json

{ "text": "Tere!" }
```

The REST API (`https://www.jutusta.ee/api/v1/*`) is ElevenLabs-compatible and also accepts
the key via the `xi-api-key: sk_jt_…` header. The whole REST surface is guarded
by the single `tts` scope.

## MCP

There is a native **MCP** endpoint at `https://www.jutusta.ee/mcp` (Streamable-HTTP,
JSON-RPC), guarded by the same bearer token. It exposes:

| Tool | Scope | What it does |
| --- | --- | --- |
| `text_to_speech` | `tts` | Synthesize speech; returns WAV audio |
| `list_voices` | `voices` | Preset voices plus the user's clones |
| `create_voice_clone` | `voices` | Clone a voice from a reference recording |
| `transcribe_url` | `asr` | Submit audio/video for transcription; returns a `job_id` |
| `get_transcription` | `asr` | Poll a job; returns the text once it succeeds |
| `list_transcriptions` | `asr` | The user's recent jobs |
| `summarize_transcription` | `summary` | Summarize a finished job |
| `list_summary_templates` | `summary` | Available summary templates |
| `translate_text` | `translate` | Translate text |
| `remove_noise` | `denoise` | Clean up an audio file; returns a `job_id` |
| `get_noise_removal` | `denoise` | Poll it; returns a download URL |

Two conventions worth knowing before you call anything:

- **Audio always goes in as a public `https` URL.** MCP has no upload
  primitive, so `audio_url` is how every tool takes media. The URL must be
  publicly reachable — Jutusta or its backend fetches it.
- **Long work is submit-then-poll.** `transcribe_url` and `remove_noise`
  return a `job_id` immediately; call the matching `get_*` tool every few
  seconds until `state` is `"succeeded"`. Nothing blocks for minutes.

Unlike REST, MCP enforces **one scope per tool family**, so a user can grant an
agent synthesis without also granting it transcription. Request every scope you
intend to use at authorize time — a token missing a tool's scope gets a
tool-level error naming it, and the fix is to re-run consent.

Full machine-readable API description: `https://www.jutusta.ee/api/v1/openapi.json`.
MCP server card: `https://www.jutusta.ee/.well-known/mcp.json`.
Human developer guide: `https://www.jutusta.ee/en/developers`.

## Scopes

`openid profile email offline_access tts asr voices summary translate denoise`

- `tts` — speech synthesis (**spends credits**). Also required for
  the entire REST API, whatever it does.
- `asr` — transcribe audio/video and read past jobs (**spends credits**).
- `voices` — list voices and create voice clones (free).
- `summary` — summarize transcriptions (**spends credits**).
- `translate` — translate text.
- `denoise` — remove noise from audio (**spends credits**).
- `openid`, `profile`, `email` — identify the user.
- `offline_access` — receive a `refresh_token`.

Discovery-only scopes let you identify the user but not spend their credits.

## Revocation

- **OAuth tokens** — the user revokes a connected agent's access from their
  Jutusta account; access tokens are opaque and validated server-side, so
  revocation takes effect immediately. When a token stops working, re-run the
  Step 3a token exchange (or refresh); if that fails, the grant was revoked —
  send the user back through Step 3a.
- **API keys** — the owning user deletes the key at `https://www.jutusta.ee/app/developers`.

## Errors

- `401` on `https://www.jutusta.ee/api/v1/*` or `https://www.jutusta.ee/mcp` → missing/expired/revoked
  credential. Follow `WWW-Authenticate` back to the Protected Resource Metadata
  and re-authorize.
- `402` → the authorizing account is out of credits. A human must top up at
  `https://www.jutusta.ee/app`.
- `403` with an `insufficient_scope` hint on `https://www.jutusta.ee/api/v1/*` → your token
  lacks `tts`; re-authorize requesting it.
- On `https://www.jutusta.ee/mcp`, a missing scope is **not** an HTTP error: the call returns
  a successful JSON-RPC result with `isError: true` and text naming the scope.
  Re-run consent requesting that scope.
