# auth.md — Dusken Agent Authentication & Registration

Dusken is an enterprise video review and collaboration platform with frame-accurate timeline annotations, Model Context Protocol (MCP) tool integration, and NLE timeline export capabilities.

## Overview & Machine-Readable Discovery

- **Service & Resource Server**: `https://dusken.io`
- **Authorization Server**: `https://dusken.io`
- **OAuth Authorization Server Metadata**: `https://dusken.io/.well-known/oauth-authorization-server`
- **OAuth Protected Resource Metadata (RFC 9728)**: `https://dusken.io/.well-known/oauth-protected-resource`
- **OpenID Connect Discovery**: `https://dusken.io/.well-known/openid-configuration`
- **MCP Server Card (SEP-1649)**: `https://dusken.io/.well-known/mcp/server-card.json`
- **Agent Skills Discovery Index**: `https://dusken.io/.well-known/agent-skills/index.json`

## Agent Registration & Auth Endpoints

- **Agent Registration URL**: `POST https://dusken.io/api/agent/register`
- **Token Endpoint**: `POST https://dusken.io/api/auth/token`
- **Credential Claim Endpoint**: `POST https://dusken.io/api/agent/claim`
- **JWKS URI**: `https://dusken.io/.well-known/jwks.json`

## Supported Authentication Methods

1. **Bearer API Keys (`Authorization: Bearer dsk_...`)**:
   - For autonomous background agents, CLI scripts, and CI/CD video rendering pipelines.
   - Provision keys via workspace settings at `https://dusken.io/settings/workspace` or through programmatic registration.

2. **Model Context Protocol (MCP) Transport Tokens**:
   - Authenticated SSE / HTTP stream connections at `https://dusken.io/api/mcp`.

3. **Identity Assertions (RFC 7523 / ID-JAG)**:
   - Supported assertion types: `urn:ietf:params:oauth:token-type:id-jag`, `verified_email`.

4. **Anonymous & Session Tokens**:
   - Time-limited reviewer sessions for guest review links.

## Supported OAuth Scopes

- `read:comments`: Retrieve timeline frame-accurate comments, drawings, and status.
- `write:comments`: Post frame-accurate comments, replies, annotations, and approvals.
- `read:assets`: Access video metadata, audio waveforms, and transcription text.
- `export:nle`: Generate markers for Adobe Premiere Pro, DaVinci Resolve, and Final Cut Pro.
- `mcp:access`: Execute Model Context Protocol tools and read Dusken resources.

## Quick Start Example (cURL)

```bash
# 1. Exchange API key or credentials for an agent bearer token
curl -X POST https://dusken.io/api/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_AGENT_ID",
    "client_secret": "YOUR_AGENT_SECRET",
    "scope": "read:comments write:comments export:nle"
  }'

# 2. Access protected endpoints with Bearer auth
curl -H "Authorization: Bearer <TOKEN>" \
  https://dusken.io/api/mcp
```