# Auth.md

## REQO agent authentication

REQO is a browser-based screen recorder and video editor. This document
describes how an automated client authenticates against reqo.me.

It is written to be accurate rather than aspirational: everything below is
implemented today. Where a capability does not exist, it says so instead of
naming an endpoint that would 404.

## Agent auth metadata

Machine-readable summary of everything in this document. The same block is
served as JSON at
[/.well-known/oauth-authorization-server](https://reqo.me/.well-known/oauth-authorization-server)
and [/.well-known/openid-configuration](https://reqo.me/.well-known/openid-configuration),
generated from one definition so the three cannot disagree.

```yaml
agent_auth:
  skill: "https://reqo.me/.well-known/agent-skills/authenticate/SKILL.md"
  documentation: "https://reqo.me/auth.md"
  register_uri: "https://reqo.me/api/auth/signin"
  registration_supported: false
  automated_registration_supported: false
  identity_types:
    - "human_delegated"
  credential_types:
    - "session_cookie"
  audience: "https://reqo.me"
  registration_methods:
    - type: "interactive_human"
      name: "Interactive sign-in"
      register_uri: "https://reqo.me/api/auth/signin"
      credential_type: "session_cookie"
      identity_type: "human_delegated"
      providers:
        - "google"
        - "email_password"
      credential_location: "cookie"
      credential_name: "__Secure-next-auth.session-token"
      verification_uri: "https://reqo.me/api/auth/session"
      revocation_uri: "https://reqo.me/api/auth/signout"
      requires_human_interaction: true
      description: "The agent cannot complete this itself. Send the user to register_uri, let them finish the flow in a browser, then forward the resulting session cookie on every request. Confirm the session at verification_uri, which returns the user or {} when there is none."
  methods:
    - type: "interactive_human"
      name: "Interactive sign-in"
      register_uri: "https://reqo.me/api/auth/signin"
      credential_type: "session_cookie"
      identity_type: "human_delegated"
      providers:
        - "google"
        - "email_password"
      credential_location: "cookie"
      credential_name: "__Secure-next-auth.session-token"
      verification_uri: "https://reqo.me/api/auth/session"
      revocation_uri: "https://reqo.me/api/auth/signout"
      requires_human_interaction: true
      description: "The agent cannot complete this itself. Send the user to register_uri, let them finish the flow in a browser, then forward the resulting session cookie on every request. Confirm the session at verification_uri, which returns the user or {} when there is none."
  claim_uri: "https://reqo.me/api/auth/session"
  revocation_uri: "https://reqo.me/api/auth/signout"
  notes: "Agents act on behalf of a signed-in human. There is no token endpoint, no client registration and no API keys. A 401 means the cookie is missing or expired and needs a fresh sign-in rather than a retry; a 403 means the session is valid but the resource is deliberately gated."
```

## Summary

| Question | Answer |
| --- | --- |
| Self-serve agent registration | Not supported |
| API keys or client credentials | Not issued |
| OAuth token endpoint | Not implemented |
| Dynamic client registration (RFC 7591) | Not implemented |
| How agents authenticate | Session cookie from an interactive human sign-in |
| Identity model | Human-delegated only |

## How to authenticate

REQO signs users in with NextAuth, using Google as the primary provider. There
is no client-credentials flow and no machine identity. An agent operates as a
signed-in human:

1. Send the user through the interactive sign-in at
   `https://reqo.me/api/auth/signin`.
2. Keep the resulting httpOnly session cookie.
3. Send that cookie with subsequent API requests.

Confirm the session at any time with `GET https://reqo.me/api/auth/session`,
which returns the current user or an empty object.

Guest recording works with no account at all. An account is required to
download a recording.

## Recognising an auth failure

A `401` means the cookie is missing, expired, or was not forwarded. Do not
retry with a backoff: send the user back through `/api/auth/signin`.

A `403` is different. The session is valid but the resource is gated
(another workspace, a Pro-only feature, or a password-protected share page).
Retrying will not help there either, and the gate is deliberate.

## Paying instead of signing in

One endpoint can be paid for per call instead of authenticated, so an agent
with no REQO account can still use it:

- `POST https://reqo.me/api/agent/transcribe` - transcription, priced per
  request and settled over [x402](https://x402.org). Call it without an
  `X-PAYMENT` header to receive a 402 describing exactly what to pay.

Payment discovery: [/.well-known/ucp](https://reqo.me/.well-known/ucp)

## What agents can do

Documented capabilities live as agent skills:

- Index: `https://reqo.me/.well-known/agent-skills/index.json`
- Authenticate (read first): `https://reqo.me/.well-known/agent-skills/authenticate/SKILL.md`
- Use the MCP server: `https://reqo.me/.well-known/agent-skills/use-mcp-server/SKILL.md`
- Create a project: `https://reqo.me/.well-known/agent-skills/create-project/SKILL.md`
- Upload a video: `https://reqo.me/.well-known/agent-skills/upload-video/SKILL.md`
- Transcribe: `https://reqo.me/.well-known/agent-skills/transcribe/SKILL.md`

Related discovery documents:

- MCP server: `https://reqo.me/mcp` (Streamable HTTP)
- MCP server card: `https://reqo.me/.well-known/mcp/server-card.json`
- API catalog: `https://reqo.me/.well-known/api-catalog`
- Protected resource metadata: `https://reqo.me/.well-known/oauth-protected-resource`
- Authorization server metadata: `https://reqo.me/.well-known/oauth-authorization-server`
- Developer portal: `https://reqo.me/developers`
- Product overview for language models: `https://reqo.me/llms.txt`

## Rate limits and conduct

Requests are rate limited per session, and responses carry the standard
`RateLimit` headers (RFC 9331) plus `Retry-After` on a 429, so an agent can
self-throttle instead of guessing.

Media endpoints serve large files, so fetch a given asset once and cache it
rather than re-requesting it per frame.

Share pages may be password protected or time limited. If a video returns 403
or 410, that gate is deliberate and should not be worked around.

## Contact

Questions about programmatic access: contact@mohbi.net