feat: developer tokens with independent OAuth grants (#367)

* feat: developer token management with listing and revocation

adds full lifecycle management for developer tokens:

**backend**
- add `is_developer_token` and `token_name` fields to UserSession model
- add GET /auth/developer-tokens endpoint to list user's tokens
- add DELETE /auth/developer-tokens/{prefix} to revoke tokens
- update POST /auth/developer-token to accept optional name parameter
- add AuthSettings config for token expiration limits
- fix connection pool leak in test fixtures (was causing TooManyConnectionsError)

**frontend**
- show existing tokens in portal with names, creation/expiration dates
- add token name input field when creating new tokens
- add revoke button for each active token
- add loading state indicator while fetching tokens

**tests**
- add 9 tests for developer token API (create, list, revoke)
- add integration test for upload/delete flow
- add `just backend integration` recipe

**docs**
- update authentication.md with token management section

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* feat: add cyclopts CLI for upload/download/list/delete

- PEP 723 inline script deps (just uv run it)
- pydantic-settings for PLYR_TOKEN/PLYR_API_URL config
- rich tables and status spinners

* refactor: rename RelaySettingsSection to AppSettingsSection

relay is the old project name

* refactor: use separate OAuth grants for developer tokens

Developer tokens now get their own OAuth credentials via a fresh
authorization flow, rather than copying credentials from the browser
session. This prevents tokens from going stale when browser sessions
refresh their tokens independently.

Changes:
- Add PendingDevToken model to store OAuth flow metadata by state
- Add POST /auth/developer-token/start to initiate OAuth for dev tokens
- Modify /auth/callback to detect dev token flows and create independent sessions
- Update frontend to redirect to PDS authorization and handle callback
- Remove old credential-copying endpoint
- Rewrite tests for new OAuth-based flow

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* docs: update authentication.md for OAuth-based dev tokens

- Update creating token flow to mention PDS authorization step
- Update API example to show /auth/developer-token/start endpoint
- Explain that tokens have independent OAuth grants, not inherited credentials
- Add PR #367 reference

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* fix: default CLI to localhost, document env overrides

- Default PLYR_API_URL to http://localhost:8001 (local dev)
- Add docstring examples for staging and production overrides
- Prevents accidental production API calls during development

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* fix: prevent dev token exchange from overwriting browser cookie

When creating a dev token via OAuth, the exchange endpoint was setting
a cookie with the dev token's session_id, overwriting the browser's
session cookie. This caused logout to delete the dev token instead of
the browser session.

Fix:
- Add is_dev_token flag to ExchangeToken model
- Pass is_dev_token=True when creating exchange token for dev tokens
- Skip cookie setting in /auth/exchange for dev token exchanges

Now dev tokens are fully independent of browser sessions.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* docs: update dev token section with CLI usage and cookie isolation

- Replace sandbox script reference with scripts/plyr.py CLI
- Add CLI examples for list/upload/download/delete
- Mention cookie isolation in how it works section

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

---------

Co-authored-by: Claude <[e-mail]>

backend/alembic/versions/2025_11_28_003756_9851b6850eb1_add_developer_token_fields_to_sessions.py

···
+"""add developer token fields to sessions
+
+Revision ID: 9851b6850eb1
+Revises: e9acf24e6885
+Create Date: 2025-11-28 00:37:56.838421
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "9851b6850eb1"
+down_revision: str | Sequence[str] | None = "e9acf24e6885"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.add_column(
+        "user_sessions",
+        sa.Column(
+            "is_developer_token", sa.Boolean(), server_default="false", nullable=False
+        ),
+    )
+    op.add_column(
+        "user_sessions", sa.Column("token_name", sa.String(length=100), nullable=True)
+    )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_column("user_sessions", "token_name")
+    op.drop_column("user_sessions", "is_developer_token")

backend/alembic/versions/2025_11_28_103800_e3d1b1eebe4b_add_pending_dev_tokens_table.py

···
+"""add pending_dev_tokens table and exchange_tokens.is_dev_token
+
+Revision ID: e3d1b1eebe4b
+Revises: 9851b6850eb1
+Create Date: 2025-11-28 10:38:00.882501
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = "e3d1b1eebe4b"
+down_revision: str | Sequence[str] | None = "9851b6850eb1"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Create pending_dev_tokens table and add is_dev_token to exchange_tokens."""
+    op.create_table(
+        "pending_dev_tokens",
+        sa.Column("state", sa.String(64), primary_key=True, index=True),
+        sa.Column("did", sa.String(256), nullable=False, index=True),
+        sa.Column("token_name", sa.String(100), nullable=True),
+        sa.Column("expires_in_days", sa.Integer(), nullable=False, server_default="90"),
+        sa.Column(
+            "created_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.func.now(),
+            index=True,
+        ),
+        sa.Column(
+            "expires_at",
+            sa.DateTime(timezone=True),
+            nullable=False,
+            server_default=sa.text("now() + interval '10 minutes'"),
+        ),
+    )
+
+    # add is_dev_token column to exchange_tokens to prevent cookie override
+    op.add_column(
+        "exchange_tokens",
+        sa.Column(
+            "is_dev_token",
+            sa.Boolean(),
+            nullable=False,
+            server_default=sa.text("false"),
+        ),
+    )
+
+
+def downgrade() -> None:
+    """Drop pending_dev_tokens table and remove is_dev_token from exchange_tokens."""
+    op.drop_column("exchange_tokens", "is_dev_token")
+    op.drop_table("pending_dev_tokens")

backend/justfile

···
     uv run pytest {{ ARGS }}
     docker compose -f tests/docker-compose.yml down
 
+# run integration tests (requires running backend and PLYRFM_API_TOKEN in .env)
+integration:
+    set -a && source ../.env && set +a && uv run pytest tests/test_integration_upload.py -m integration -v -s
+
 # run type checking and linting
 lint:
     uv run ty check

backend/src/backend/_internal/__init__.py

···
 """internal relay modules."""
 
 from backend._internal.auth import (
+    DeveloperToken,
+    PendingDevTokenData,
     Session,
     check_artist_profile_exists,
     consume_exchange_token,
     create_exchange_token,
     create_session,
+    delete_pending_dev_token,
     delete_session,
+    get_pending_dev_token,
     get_session,
     handle_oauth_callback,
+    list_developer_tokens,
     oauth_client,
     require_artist_profile,
     require_auth,
+    revoke_developer_token,
+    save_pending_dev_token,
     start_oauth_flow,
     update_session_tokens,
 )
···
 from backend._internal.queue import queue_service
 
 __all__ = [
+    "DeveloperToken",
+    "PendingDevTokenData",
     "Session",
     "check_artist_profile_exists",
     "consume_exchange_token",
     "create_exchange_token",
     "create_session",
+    "delete_pending_dev_token",
     "delete_session",
     "get_like_count_safe",
+    "get_pending_dev_token",
     "get_session",
     "handle_oauth_callback",
+    "list_developer_tokens",
     "notification_service",
     "oauth_client",
     "queue_service",
     "require_artist_profile",
     "require_auth",
+    "revoke_developer_token",
+    "save_pending_dev_token",
     "start_oauth_flow",
     "update_session_tokens",
 ]

backend/src/backend/_internal/auth.py

···
 
 from backend._internal.oauth_stores import PostgresStateStore
 from backend.config import settings
-from backend.models import ExchangeToken, UserSession
+from backend.models import ExchangeToken, PendingDevToken, UserSession
 from backend.utilities.database import db_session
 
 logger = logging.getLogger(__name__)
···
         return None
 
 
-async def create_session(did: str, handle: str, oauth_session: dict[str, Any]) -> str:
-    """create a new session for authenticated user with encrypted OAuth data."""
+async def create_session(
+    did: str,
+    handle: str,
+    oauth_session: dict[str, Any],
+    expires_in_days: int = 14,
+    is_developer_token: bool = False,
+    token_name: str | None = None,
+) -> str:
+    """create a new session for authenticated user with encrypted OAuth data.
+
+    args:
+        did: user's decentralized identifier
+        handle: user's ATProto handle
+        oauth_session: OAuth session data to encrypt and store
+        expires_in_days: session expiration in days (default 14, use 0 for no expiration)
+        is_developer_token: whether this is a developer token (for listing/revocation)
+        token_name: optional name for the token (only for developer tokens)
+    """
     session_id = secrets.token_urlsafe(32)
 
     # encrypt sensitive OAuth session data before storing
     encrypted_data = _encrypt_data(json.dumps(oauth_session))
 
-    # store in database with expiration (2 weeks from now per OAuth 2.1 requirements)
-    expires_at = datetime.now(UTC) + timedelta(days=14)
+    # store in database with expiration
+    expires_at = (
+        datetime.now(UTC) + timedelta(days=expires_in_days)
+        if expires_in_days > 0
+        else None
+    )
 
     async with db_session() as db:
         user_session = UserSession(
···
             handle=handle,
             oauth_session_data=encrypted_data,
             expires_at=expires_at,
+            is_developer_token=is_developer_token,
+            token_name=token_name,
         )
         db.add(user_session)
         await db.commit()
···
         return artist is not None
 
 
-async def create_exchange_token(session_id: str) -> str:
+async def create_exchange_token(session_id: str, is_dev_token: bool = False) -> str:
     """create a one-time use exchange token for secure OAuth callback.
 
     exchange tokens expire after 60 seconds and can only be used once,
     preventing session_id exposure in browser history/referrers.
+
+    args:
+        session_id: the session to associate with this exchange token
+        is_dev_token: if True, the exchange will not set a browser cookie
     """
     token = secrets.token_urlsafe(32)
 
···
         exchange_token = ExchangeToken(
             token=token,
             session_id=session_id,
+            is_dev_token=is_dev_token,
         )
         db.add(exchange_token)
         await db.commit()
···
     return token
 
 
-async def consume_exchange_token(token: str) -> str | None:
-    """consume an exchange token and return the associated session_id.
+async def consume_exchange_token(token: str) -> tuple[str, bool] | None:
+    """consume an exchange token and return (session_id, is_dev_token).
 
     returns None if token is invalid, expired, or already used.
     uses atomic UPDATE to prevent race conditions (token can only be used once).
···
         if datetime.now(UTC) > exchange_token.expires_at:
             return None
 
+        # capture is_dev_token before atomic update
+        is_dev_token = exchange_token.is_dev_token
+
         # atomically mark as used ONLY if not already used
         # this prevents race conditions where two requests try to use the same token
         result = await db.execute(
···
 
         # if no rows were updated, token was already used
         session_id = result.scalar_one_or_none()
-        return session_id
+        if session_id is None:
+            return None
+
+        return session_id, is_dev_token
 
 
 async def require_auth(
···
         )
 
     return session
+
+
+@dataclass
+class DeveloperToken:
+    """developer token metadata (without sensitive session data)."""
+
+    session_id: str
+    token_name: str | None
+    created_at: datetime
+    expires_at: datetime | None
+
+
+async def list_developer_tokens(did: str) -> list[DeveloperToken]:
+    """list all developer tokens for a user."""
+    async with db_session() as db:
+        result = await db.execute(
+            select(UserSession).where(
+                UserSession.did == did,
+                UserSession.is_developer_token == True,  # noqa: E712
+            )
+        )
+        sessions = result.scalars().all()
+
+        tokens = []
+        for session in sessions:
+            # check if expired
+            if session.expires_at and datetime.now(UTC) > session.expires_at:
+                continue  # skip expired tokens
+
+            tokens.append(
+                DeveloperToken(
+                    session_id=session.session_id,
+                    token_name=session.token_name,
+                    created_at=session.created_at,
+                    expires_at=session.expires_at,
+                )
+            )
+
+        return tokens
+
+
+async def revoke_developer_token(did: str, session_id: str) -> bool:
+    """revoke a developer token. returns True if successful, False if not found."""
+    async with db_session() as db:
+        result = await db.execute(
+            select(UserSession).where(
+                UserSession.session_id == session_id,
+                UserSession.did == did,  # ensure user owns this token
+                UserSession.is_developer_token == True,  # noqa: E712
+            )
+        )
+        session = result.scalar_one_or_none()
+
+        if not session:
+            return False
+
+        await db.delete(session)
+        await db.commit()
+        return True
+
+
+@dataclass
+class PendingDevTokenData:
+    """metadata for a pending developer token OAuth flow."""
+
+    state: str
+    did: str
+    token_name: str | None
+    expires_in_days: int
+
+
+async def save_pending_dev_token(
+    state: str,
+    did: str,
+    token_name: str | None,
+    expires_in_days: int,
+) -> None:
+    """save pending dev token metadata keyed by OAuth state."""
+    async with db_session() as db:
+        pending = PendingDevToken(
+            state=state,
+            did=did,
+            token_name=token_name,
+            expires_in_days=expires_in_days,
+        )
+        db.add(pending)
+        await db.commit()
+
+
+async def get_pending_dev_token(state: str) -> PendingDevTokenData | None:
+    """get pending dev token metadata by OAuth state."""
+    async with db_session() as db:
+        result = await db.execute(
+            select(PendingDevToken).where(PendingDevToken.state == state)
+        )
+        pending = result.scalar_one_or_none()
+
+        if not pending:
+            return None
+
+        # check if expired
+        if datetime.now(UTC) > pending.expires_at:
+            await db.delete(pending)
+            await db.commit()
+            return None
+
+        return PendingDevTokenData(
+            state=pending.state,
+            did=pending.did,
+            token_name=pending.token_name,
+            expires_in_days=pending.expires_in_days,
+        )
+
+
+async def delete_pending_dev_token(state: str) -> None:
+    """delete pending dev token metadata after use."""
+    async with db_session() as db:
+        result = await db.execute(
+            select(PendingDevToken).where(PendingDevToken.state == state)
+        )
+        if pending := result.scalar_one_or_none():
+            await db.delete(pending)
+            await db.commit()

backend/src/backend/api/auth.py

···
     consume_exchange_token,
     create_exchange_token,
     create_session,
+    delete_pending_dev_token,
     delete_session,
+    get_pending_dev_token,
     handle_oauth_callback,
+    list_developer_tokens,
     require_auth,
+    revoke_developer_token,
+    save_pending_dev_token,
     start_oauth_flow,
 )
 from backend.config import settings
···
 
     returns exchange token in URL which frontend will exchange for session_id.
     exchange token is short-lived (60s) and one-time use for security.
+
+    if this is a developer token flow (state exists in pending_dev_tokens),
+    creates a dev token session and redirects with dev_token=true flag.
     """
     did, handle, oauth_session = await handle_oauth_callback(code, state, iss)
+
+    # check if this is a developer token OAuth flow
+    pending_dev_token = await get_pending_dev_token(state)
+
+    if pending_dev_token:
+        # verify the DID matches (user must be the one who started the flow)
+        if pending_dev_token.did != did:
+            raise HTTPException(
+                status_code=403,
+                detail="developer token flow was started by a different user",
+            )
+
+        # create dev token session with its own OAuth credentials
+        session_id = await create_session(
+            did=did,
+            handle=handle,
+            oauth_session=oauth_session,
+            expires_in_days=pending_dev_token.expires_in_days,
+            is_developer_token=True,
+            token_name=pending_dev_token.token_name,
+        )
+
+        # clean up pending record
+        await delete_pending_dev_token(state)
+
+        # create exchange token (marked as dev token to prevent cookie override)
+        exchange_token = await create_exchange_token(session_id, is_dev_token=True)
+
+        return RedirectResponse(
+            url=f"{settings.frontend.url}/portal?exchange_token={exchange_token}&dev_token=true",
+            status_code=303,
+        )
+
+    # regular login flow
     session_id = await create_session(did, handle, oauth_session)
 
     # create one-time exchange token (expires in 60 seconds)
···
 
     for browser requests: sets HttpOnly cookie and still returns session_id in response
     for SDK/CLI clients: only returns session_id in response (no cookie)
+    for dev token exchanges: returns session_id but does NOT set cookie
     """
-    session_id = await consume_exchange_token(exchange_request.exchange_token)
+    result = await consume_exchange_token(exchange_request.exchange_token)
 
-    if not session_id:
+    if not result:
         raise HTTPException(
             status_code=401,
             detail="invalid, expired, or already used exchange token",
         )
+
+    session_id, is_dev_token = result
+
+    # don't set cookie for dev token exchanges - this prevents overwriting
+    # the browser's session cookie when creating a dev token
+    if is_dev_token:
+        return ExchangeTokenResponse(session_id=session_id)
 
     user_agent = request.headers.get("user-agent", "").lower()
     is_browser = any(
···
         did=session.did,
         handle=session.handle,
     )
+
+
+class DeveloperTokenInfo(BaseModel):
+    """info about a developer token (without the actual token)."""
+
+    session_id: str  # first 8 chars only for identification
+    name: str | None
+    created_at: str  # ISO format
+    expires_at: str | None  # ISO format or null for never
+
+
+class DeveloperTokenListResponse(BaseModel):
+    """response model for listing developer tokens."""
+
+    tokens: list[DeveloperTokenInfo]
+
+
[e-mail]("/developer-tokens")
+async def get_developer_tokens(
+    session: Session = Depends(require_auth),
+) -> DeveloperTokenListResponse:
+    """list all developer tokens for the current user."""
+    tokens = await list_developer_tokens(session.did)
+
+    return DeveloperTokenListResponse(
+        tokens=[
+            DeveloperTokenInfo(
+                session_id=t.session_id[:8],  # only show prefix for identification
+                name=t.token_name,
+                created_at=t.created_at.isoformat(),
+                expires_at=t.expires_at.isoformat() if t.expires_at else None,
+            )
+            for t in tokens
+        ]
+    )
+
+
[e-mail]("/developer-tokens/{token_prefix}")
+async def delete_developer_token(
+    token_prefix: str,
+    session: Session = Depends(require_auth),
+) -> JSONResponse:
+    """revoke a developer token by its prefix (first 8 chars of session_id)."""
+    # find the full session_id from prefix
+    tokens = await list_developer_tokens(session.did)
+    matching = [t for t in tokens if t.session_id.startswith(token_prefix)]
+
+    if not matching:
+        raise HTTPException(status_code=404, detail="token not found")
+
+    if len(matching) > 1:
+        raise HTTPException(
+            status_code=400,
+            detail="ambiguous prefix - provide more characters",
+        )
+
+    success = await revoke_developer_token(session.did, matching[0].session_id)
+    if not success:
+        raise HTTPException(status_code=404, detail="token not found")
+
+    return JSONResponse(content={"message": "token revoked successfully"})
+
+
+class DevTokenStartRequest(BaseModel):
+    """request model for starting developer token OAuth flow."""
+
+    name: str | None = None
+    expires_in_days: int | None = None
+
+
+class DevTokenStartResponse(BaseModel):
+    """response model with OAuth authorization URL."""
+
+    auth_url: str
+
+
[e-mail]("/developer-token/start")
[e-mail](settings.rate_limit.auth_limit)
+async def start_developer_token_flow(
+    request: Request,
+    body: DevTokenStartRequest,
+    session: Session = Depends(require_auth),
+) -> DevTokenStartResponse:
+    """start OAuth flow to create a developer token with its own credentials.
+
+    this initiates a new OAuth authorization flow. the user will be redirected
+    to authorize, and on callback a dev token with independent OAuth credentials
+    will be created. this ensures dev tokens don't become stale when browser
+    sessions refresh their tokens.
+
+    returns the authorization URL that the frontend should redirect to.
+    """
+    # validate expiration
+    expires_in_days = (
+        body.expires_in_days
+        if body.expires_in_days is not None
+        else settings.auth.developer_token_default_days
+    )
+
+    max_days = settings.auth.developer_token_max_days
+    if expires_in_days > max_days:
+        raise HTTPException(
+            status_code=400,
+            detail=f"expires_in_days cannot exceed {max_days} (use 0 for no expiration)",
+        )
+
+    # start OAuth flow using the user's handle
+    auth_url, state = await start_oauth_flow(session.handle)
+
+    # save pending dev token metadata keyed by state
+    await save_pending_dev_token(
+        state=state,
+        did=session.did,
+        token_name=body.name,
+        expires_in_days=expires_in_days,
+    )
+
+    return DevTokenStartResponse(auth_url=auth_url)

backend/src/backend/config.py

···
-"""Relay configuration using nested Pydantic settings."""
+"""plyr.fm configuration using nested Pydantic settings."""
 
 from __future__ import annotations
 
···
 BASE_DIR = Path(__file__).resolve().parents[2]
 
 
-class RelaySettingsSection(BaseSettings):
+class AppSettingsSection(BaseSettings):
     """Base class for all settings sections with shared defaults."""
 
     model_config = SettingsConfigDict(
···
     )
 
 
-class NotificationBotSettings(RelaySettingsSection):
+class NotificationBotSettings(AppSettingsSection):
     """Settings for the notification bot."""
 
     model_config = SettingsConfigDict(
···
     password: str = Field(default="", description="App password for bot")
 
 
-class NotificationSettings(RelaySettingsSection):
+class NotificationSettings(AppSettingsSection):
     """Settings for notifications."""
 
     model_config = SettingsConfigDict(
···
     )
 
 
-class AppSettings(RelaySettingsSection):
+class AppSettings(AppSettingsSection):
     """Core application configuration."""
 
     name: str = Field(
···
     )
 
 
-class FrontendSettings(RelaySettingsSection):
+class FrontendSettings(AppSettingsSection):
     """Frontend-specific configuration."""
 
     url: str = Field(
···
             return r"^(http://localhost:5173)$"
 
 
-class DatabaseSettings(RelaySettingsSection):
+class DatabaseSettings(AppSettingsSection):
     """Database configuration."""
 
     url: str = Field(
···
     )
 
 
-class StorageSettings(RelaySettingsSection):
+class StorageSettings(AppSettingsSection):
     """Asset storage configuration (R2 only)."""
 
     max_upload_size_mb: int = Field(
···
         return True
 
 
-class AtprotoSettings(RelaySettingsSection):
+class AtprotoSettings(AppSettingsSection):
     """ATProto integration settings."""
 
     pds_url: str = Field(
···
         return f"atproto {' '.join(scopes)}"
 
 
-class ObservabilitySettings(RelaySettingsSection):
+class ObservabilitySettings(AppSettingsSection):
     """Observability configuration."""
 
     enabled: bool = Field(
···
     )
 
 
-class RateLimitSettings(RelaySettingsSection):
+class RateLimitSettings(AppSettingsSection):
     """Rate limiting configuration."""
 
     model_config = SettingsConfigDict(
···
     )
 
 
-class Settings(RelaySettingsSection):
+class AuthSettings(AppSettingsSection):
+    """Authentication configuration."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="AUTH_",
+        env_file=".env",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    developer_token_default_days: int = Field(
+        default=90,
+        description="Default expiration in days for developer tokens (0 = no expiration)",
+    )
+    developer_token_max_days: int = Field(
+        default=365,
+        description="Maximum allowed expiration in days for developer tokens",
+    )
+
+
+class Settings(AppSettingsSection):
     """Relay application settings."""
 
     model_config = SettingsConfigDict(
···
     rate_limit: RateLimitSettings = Field(
         default_factory=RateLimitSettings,
         description="Rate limiting settings",
+    )
+    auth: AuthSettings = Field(
+        default_factory=AuthSettings,
+        description="Authentication settings",
     )
     notify: NotificationSettings = Field(
         default_factory=NotificationSettings,

backend/src/backend/models/__init__.py

···
 from backend.models.exchange_token import ExchangeToken
 from backend.models.job import Job
 from backend.models.oauth_state import OAuthStateModel
+from backend.models.pending_dev_token import PendingDevToken
 from backend.models.preferences import UserPreferences
 from backend.models.queue import QueueState
 from backend.models.session import UserSession
···
     "ExchangeToken",
     "Job",
     "OAuthStateModel",
+    "PendingDevToken",
     "QueueState",
     "ScanResolution",
     "Track",

backend/src/backend/models/exchange_token.py

···
 
 from datetime import UTC, datetime, timedelta
 
-from sqlalchemy import DateTime, String
+from sqlalchemy import Boolean, DateTime, String
 from sqlalchemy.orm import Mapped, mapped_column
 
 from backend.models.database import Base
···
         nullable=False,
     )
     used: Mapped[bool] = mapped_column(default=False, nullable=False)
+    # dev token exchanges should not set browser cookies
+    is_dev_token: Mapped[bool] = mapped_column(
+        Boolean, default=False, nullable=False, server_default="false"
+    )

backend/src/backend/models/pending_dev_token.py

···
+"""pending developer token model for OAuth flow metadata."""
+
+from datetime import UTC, datetime, timedelta
+
+from sqlalchemy import DateTime, Integer, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from backend.models.database import Base
+
+
+class PendingDevToken(Base):
+    """temporary record linking OAuth state to dev token creation metadata.
+
+    when a user initiates the OAuth flow for creating a developer token,
+    we store the token name and expiration here, keyed by the OAuth state.
+    the callback checks this table to know if the flow is for a dev token.
+
+    records expire after 10 minutes (matching OAuth state TTL).
+    """
+
+    __tablename__ = "pending_dev_tokens"
+
+    state: Mapped[str] = mapped_column(String(64), primary_key=True, index=True)
+    did: Mapped[str] = mapped_column(String(256), nullable=False, index=True)
+    token_name: Mapped[str | None] = mapped_column(String(100), nullable=True)
+    expires_in_days: Mapped[int] = mapped_column(Integer, nullable=False, default=90)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC),
+        nullable=False,
+        index=True,  # for cleanup queries
+    )
+    expires_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC) + timedelta(minutes=10),
+        nullable=False,
+    )

backend/src/backend/models/session.py

···
 
 from datetime import UTC, datetime
 
-from sqlalchemy import DateTime, String, Text
+from sqlalchemy import Boolean, DateTime, String, Text
 from sqlalchemy.orm import Mapped, mapped_column
 
 from backend.models.database import Base
···
     expires_at: Mapped[datetime | None] = mapped_column(
         DateTime(timezone=True), nullable=True
     )
+    # developer token fields
+    is_developer_token: Mapped[bool] = mapped_column(
+        Boolean, default=False, nullable=False, server_default="false"
+    )
+    token_name: Mapped[str | None] = mapped_column(String(100), nullable=True)

backend/tests/api/test_developer_tokens.py

···
+"""tests for developer token api endpoints."""
+
+from collections.abc import Generator
+from unittest.mock import AsyncMock, patch
+
+import pytest
+from fastapi import FastAPI
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend._internal import Session, create_session, require_auth
+from backend.main import app
+
+
+class MockSession(Session):
+    """mock session for auth bypass in tests."""
+
+    def __init__(self, did: str = "did:test:user123"):
+        self.did = did
+        self.handle = "testuser.bsky.social"
+        self.session_id = "test_session_id"
+        self.access_token = "test_token"
+        self.refresh_token = "test_refresh"
+        self.oauth_session = {
+            "did": did,
+            "handle": "testuser.bsky.social",
+            "pds_url": "https://test.pds",
+            "authserver_iss": "https://auth.test",
+            "scope": "atproto transition:generic",
+            "access_token": "test_token",
+            "refresh_token": "test_refresh",
+            "dpop_private_key_pem": "fake_key",
+            "dpop_authserver_nonce": "",
+            "dpop_pds_nonce": "",
+        }
+
+
[e-mail]
+def test_app(db_session: AsyncSession) -> Generator[FastAPI, None, None]:
+    """create test app with mocked auth."""
+
+    async def mock_require_auth() -> Session:
+        return MockSession()
+
+    app.dependency_overrides[require_auth] = mock_require_auth
+
+    yield app
+
+    app.dependency_overrides.clear()
+
+
+async def test_start_developer_token_flow(test_app: FastAPI, db_session: AsyncSession):
+    """test starting the developer token OAuth flow."""
+    with patch(
+        "backend.api.auth.start_oauth_flow", new_callable=AsyncMock
+    ) as mock_oauth:
+        mock_oauth.return_value = (
+            "https://auth.example.com/authorize?...",
+            "test_state",
+        )
+
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await client.post(
+                "/auth/developer-token/start",
+                json={"name": "my-token", "expires_in_days": 30},
+            )
+
+        assert response.status_code == 200
+        data = response.json()
+        assert "auth_url" in data
+        assert data["auth_url"].startswith("https://auth.example.com")
+        mock_oauth.assert_called_once_with("testuser.bsky.social")
+
+
+async def test_start_developer_token_default_expiration(
+    test_app: FastAPI, db_session: AsyncSession
+):
+    """test starting dev token flow with default expiration."""
+    with patch(
+        "backend.api.auth.start_oauth_flow", new_callable=AsyncMock
+    ) as mock_oauth:
+        mock_oauth.return_value = ("https://auth.example.com/authorize", "test_state")
+
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await client.post(
+                "/auth/developer-token/start",
+                json={},
+            )
+
+        assert response.status_code == 200
+        # verify pending dev token was saved (would fail if expiration wasn't set)
+
+
+async def test_start_developer_token_exceeds_max(
+    test_app: FastAPI, db_session: AsyncSession
+):
+    """test that expiration cannot exceed max allowed."""
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.post(
+            "/auth/developer-token/start",
+            json={"expires_in_days": 999},  # exceeds default max of 365
+        )
+
+    assert response.status_code == 400
+    assert "cannot exceed" in response.json()["detail"]
+
+
+async def test_start_developer_token_requires_auth(db_session: AsyncSession):
+    """test that developer token start requires authentication."""
+    async with AsyncClient(
+        transport=ASGITransport(app=app), base_url="http://test"
+    ) as client:
+        response = await client.post(
+            "/auth/developer-token/start",
+            json={},
+        )
+
+    assert response.status_code == 401
+
+
+async def test_list_developer_tokens(test_app: FastAPI, db_session: AsyncSession):
+    """test listing developer tokens."""
+    mock_session = MockSession()
+
+    # create a dev token directly in the database
+    await create_session(
+        did=mock_session.did,
+        handle=mock_session.handle,
+        oauth_session=mock_session.oauth_session,
+        expires_in_days=30,
+        is_developer_token=True,
+        token_name="list-test-token",
+    )
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get("/auth/developer-tokens")
+
+    assert response.status_code == 200
+    data = response.json()
+    assert "tokens" in data
+    assert len(data["tokens"]) >= 1
+
+    # find our token
+    token = next((t for t in data["tokens"] if t["name"] == "list-test-token"), None)
+    assert token is not None
+    assert "session_id" in token
+    assert "created_at" in token
+
+
+async def test_revoke_developer_token(test_app: FastAPI, db_session: AsyncSession):
+    """test revoking a developer token."""
+    mock_session = MockSession()
+
+    # create a dev token directly
+    await create_session(
+        did=mock_session.did,
+        handle=mock_session.handle,
+        oauth_session=mock_session.oauth_session,
+        expires_in_days=30,
+        is_developer_token=True,
+        token_name="revoke-test-token",
+    )
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        # list tokens to get session_id prefix
+        list_response = await client.get("/auth/developer-tokens")
+        assert list_response.status_code == 200
+        tokens = list_response.json()["tokens"]
+        token = next((t for t in tokens if t["name"] == "revoke-test-token"), None)
+        assert token is not None
+
+        # revoke the token
+        revoke_response = await client.delete(
+            f"/auth/developer-tokens/{token['session_id']}"
+        )
+        assert revoke_response.status_code == 200
+        assert revoke_response.json()["message"] == "token revoked successfully"
+
+        # verify it's gone
+        final_list = await client.get("/auth/developer-tokens")
+        remaining = [
+            t for t in final_list.json()["tokens"] if t["name"] == "revoke-test-token"
+        ]
+        assert len(remaining) == 0
+
+
+async def test_revoke_nonexistent_token(test_app: FastAPI, db_session: AsyncSession):
+    """test revoking a token that doesn't exist."""
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.delete("/auth/developer-tokens/nonexist")
+
+    assert response.status_code == 404
+    assert response.json()["detail"] == "token not found"

backend/tests/conftest.py

···
 
 
 @pytest.fixture()
-async def _engine(test_database_url: str, _database_setup: None) -> AsyncEngine:
+async def _engine(
+    test_database_url: str, _database_setup: None
+) -> AsyncGenerator[AsyncEngine, None]:
     """create a database engine for each test (to avoid event loop issues)."""
-    return create_async_engine(
+    engine = create_async_engine(
         test_database_url,
         echo=False,
+        pool_size=2,
+        max_overflow=0,
     )
+    try:
+        yield engine
+    finally:
+        await engine.dispose()
 
 
 @pytest.fixture()

backend/tests/test_auth.py

···
     token = await create_exchange_token(session_id)
 
     # verify token can be consumed (proves it was created correctly)
-    returned_session_id = await consume_exchange_token(token)
+    result = await consume_exchange_token(token)
+    assert result is not None
+    returned_session_id, is_dev_token = result
     assert returned_session_id == session_id
+    assert is_dev_token is False
 
     # verify token can't be reused
     second_attempt = await consume_exchange_token(token)
···
     token = await create_exchange_token(session_id)
 
     # consume token
-    returned_session_id = await consume_exchange_token(token)
+    result = await consume_exchange_token(token)
+    assert result is not None
+    returned_session_id, is_dev_token = result
     assert returned_session_id == session_id
+    assert is_dev_token is False
 
     # verify token can't be consumed again (proves it was marked as used)
     second_attempt = await consume_exchange_token(token)
···
     token = await create_exchange_token(session_id)
 
     # consume token first time
-    first_result = await consume_exchange_token(token)
-    assert first_result == session_id
+    result = await consume_exchange_token(token)
+    assert result is not None
+    returned_session_id, is_dev_token = result
+    assert returned_session_id == session_id
 
     # try to consume again - should return None
     second_result = await consume_exchange_token(token)
···
     result = await db_session.execute(select(ExchangeToken))
     tokens = result.scalars().all()
     assert len(tokens) == 0
+
+
+async def test_create_session_with_custom_expiration(db_session: AsyncSession):
+    """verify session creation with custom expiration works."""
+    did = "did:plc:customexp123"
+    handle = "customexp.bsky.social"
+    oauth_data = {"access_token": "token", "refresh_token": "refresh"}
+
+    # create session with 30-day expiration
+    session_id = await create_session(did, handle, oauth_data, expires_in_days=30)
+
+    # verify session exists and works
+    session = await get_session(session_id)
+    assert session is not None
+    assert session.did == did
+
+    # verify expiration is set (within reasonable range)
+    result = await db_session.execute(
+        select(UserSession).where(UserSession.session_id == session_id)
+    )
+    db_session_record = result.scalar_one_or_none()
+    assert db_session_record is not None
+    assert db_session_record.expires_at is not None
+
+    # should expire roughly 30 days from now
+    expected_expiry = datetime.now(UTC) + timedelta(days=30)
+    actual_expiry = db_session_record.expires_at.replace(tzinfo=UTC)
+    diff = abs((expected_expiry - actual_expiry).total_seconds())
+    assert diff < 60  # within 1 minute
+
+
+async def test_create_session_with_no_expiration(db_session: AsyncSession):
+    """verify session creation with expires_in_days=0 creates non-expiring session."""
+    did = "did:plc:noexp123"
+    handle = "noexp.bsky.social"
+    oauth_data = {"access_token": "token", "refresh_token": "refresh"}
+
+    # create session with no expiration
+    session_id = await create_session(did, handle, oauth_data, expires_in_days=0)
+
+    # verify session exists
+    session = await get_session(session_id)
+    assert session is not None
+    assert session.did == did
+
+    # verify expires_at is None
+    result = await db_session.execute(
+        select(UserSession).where(UserSession.session_id == session_id)
+    )
+    db_session_record = result.scalar_one_or_none()
+    assert db_session_record is not None
+    assert db_session_record.expires_at is None
+
+
+async def test_create_session_default_expiration(db_session: AsyncSession):
+    """verify session creation uses default 14-day expiration."""
+    did = "did:plc:defaultexp123"
+    handle = "defaultexp.bsky.social"
+    oauth_data = {"access_token": "token", "refresh_token": "refresh"}
+
+    # create session with default expiration
+    session_id = await create_session(did, handle, oauth_data)
+
+    # verify expiration is set to default (14 days)
+    result = await db_session.execute(
+        select(UserSession).where(UserSession.session_id == session_id)
+    )
+    db_session_record = result.scalar_one_or_none()
+    assert db_session_record is not None
+    assert db_session_record.expires_at is not None
+
+    expected_expiry = datetime.now(UTC) + timedelta(days=14)
+    actual_expiry = db_session_record.expires_at.replace(tzinfo=UTC)
+    diff = abs((expected_expiry - actual_expiry).total_seconds())
+    assert diff < 60  # within 1 minute

backend/tests/test_integration_upload.py

···
+"""integration tests for track upload/delete using real API token.
+
+these tests require:
+- PLYRFM_API_TOKEN or PLYR_TOKEN env var
+- running backend (local or remote)
+- set PLYR_API_URL for non-local testing (default: http://localhost:8001)
+
+run with: uv run pytest tests/test_integration_upload.py -m integration -v
+"""
+
+import json
+import os
+import struct
+import tempfile
+from collections.abc import Generator
+from pathlib import Path
+
+import httpx
+import pytest
+
+API_URL = os.getenv("PLYR_API_URL", "http://localhost:8001")
+TOKEN = os.getenv("PLYR_TOKEN") or os.getenv("PLYRFM_API_TOKEN")
+
+
+def generate_wav_file(duration_seconds: float = 1.0, sample_rate: int = 44100) -> bytes:
+    """generate a minimal valid WAV file with silence."""
+    num_channels = 1
+    bits_per_sample = 16
+    num_samples = int(sample_rate * duration_seconds)
+    data_size = num_samples * num_channels * (bits_per_sample // 8)
+
+    # WAV header
+    header = struct.pack(
+        "<4sI4s4sIHHIIHH4sI",
+        b"RIFF",
+        36 + data_size,  # file size - 8
+        b"WAVE",
+        b"fmt ",
+        16,  # fmt chunk size
+        1,  # audio format (PCM)
+        num_channels,
+        sample_rate,
+        sample_rate * num_channels * (bits_per_sample // 8),  # byte rate
+        num_channels * (bits_per_sample // 8),  # block align
+        bits_per_sample,
+        b"data",
+        data_size,
+    )
+
+    # silence (zeros)
+    audio_data = b"\x00" * data_size
+
+    return header + audio_data
+
+
[e-mail]
+def test_audio_file() -> Generator[Path, None, None]:
+    """create a temporary test audio file."""
+    wav_data = generate_wav_file(duration_seconds=1.0)
+
+    with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+        f.write(wav_data)
+        path = Path(f.name)
+
+    yield path
+
+    # cleanup
+    path.unlink(missing_ok=True)
+
+
[e-mail]
+async def test_upload_and_delete_track(test_audio_file: Path):
+    """integration test: upload a track, wait for processing, then delete it."""
+    if not TOKEN:
+        pytest.skip("PLYR_TOKEN or PLYRFM_API_TOKEN not set")
+
+    async with httpx.AsyncClient(timeout=120.0) as client:
+        # 1. verify auth works
+        auth_response = await client.get(
+            f"{API_URL}/auth/me",
+            headers={"Authorization": f"Bearer {TOKEN}"},
+        )
+        if auth_response.status_code == 401:
+            pytest.skip("token is invalid or expired")
+        assert auth_response.status_code == 200, f"auth failed: {auth_response.text}"
+        user = auth_response.json()
+        print(f"authenticated as: {user['handle']}")
+
+        # 2. upload track
+        with open(test_audio_file, "rb") as f:
+            files = {"file": ("test_integration.wav", f, "audio/wav")}
+            data = {"title": "Integration Test Track (DELETE ME)"}
+
+            upload_response = await client.post(
+                f"{API_URL}/tracks/",
+                headers={"Authorization": f"Bearer {TOKEN}"},
+                files=files,
+                data=data,
+            )
+
+        if upload_response.status_code == 403:
+            detail = upload_response.json().get("detail", "")
+            if "artist_profile_required" in detail:
+                pytest.skip("user needs artist profile setup")
+            if "scope_upgrade_required" in detail:
+                pytest.skip("token needs re-authorization with new scopes")
+
+        assert upload_response.status_code == 200, (
+            f"upload failed: {upload_response.text}"
+        )
+
+        upload_data = upload_response.json()
+        upload_id = upload_data["upload_id"]
+        print(f"upload started: {upload_id}")
+
+        # 3. poll for completion via SSE
+        track_id = None
+        async with client.stream(
+            "GET",
+            f"{API_URL}/tracks/uploads/{upload_id}/progress",
+            headers={"Authorization": f"Bearer {TOKEN}"},
+        ) as response:
+            async for line in response.aiter_lines():
+                if line.startswith("data: "):
+                    data = json.loads(line[6:])
+                    status = data.get("status")
+                    print(f"  status: {status} - {data.get('message', '')}")
+
+                    if status == "completed":
+                        track_id = data.get("track_id")
+                        print(f"upload complete! track_id: {track_id}")
+                        break
+                    elif status == "failed":
+                        error = data.get("error", "unknown error")
+                        pytest.fail(f"upload failed: {error}")
+
+        assert track_id is not None, "upload completed but no track_id returned"
+
+        # 4. verify track exists
+        track_response = await client.get(f"{API_URL}/tracks/{track_id}")
+        assert track_response.status_code == 200, (
+            f"track not found: {track_response.text}"
+        )
+        track = track_response.json()
+        print(f"track created: {track['title']} by {track['artist']['handle']}")
+
+        # 5. delete track
+        delete_response = await client.delete(
+            f"{API_URL}/tracks/{track_id}",
+            headers={"Authorization": f"Bearer {TOKEN}"},
+        )
+        assert delete_response.status_code == 200, (
+            f"delete failed: {delete_response.text}"
+        )
+        print(f"track {track_id} deleted successfully")
+
+        # 6. verify track is gone
+        verify_response = await client.get(f"{API_URL}/tracks/{track_id}")
+        assert verify_response.status_code == 404, "track should be deleted"
+        print("verified track no longer exists")

docs/authentication.md

···
 2. frontend and backend both on `localhost` (not `127.0.0.1`)?
 3. backend using `secure=False` for localhost?
 
+## developer tokens (programmatic access)
+
+for scripts, CLIs, and automated workflows, create a long-lived developer token:
+
+### creating a token
+
+**via UI (recommended)**:
+1. go to portal → "your data" → "developer tokens" section
+2. optionally enter a name (e.g., "upload-script", "ci-pipeline")
+3. select expiration (30/90/180/365 days or never)
+4. click "create token"
+5. **authorize at your PDS** (you'll be redirected to approve the OAuth grant)
+6. copy the token immediately after redirect (shown only once)
+
+**via API**:
+```javascript
+// step 1: start OAuth flow (returns auth_url to redirect to)
+const response = await fetch('/auth/developer-token/start', {
+    method: 'POST',
+    headers: {'Content-Type': 'application/json'},
+    credentials: 'include',
+    body: JSON.stringify({ name: 'my-script', expires_in_days: 90 })
+});
+const { auth_url } = await response.json();
+// step 2: redirect user to auth_url to authorize at their PDS
+// step 3: on callback, token is returned via exchange flow
+```
+
+### managing tokens
+
+**list active tokens**:
+the portal shows all your active developer tokens with:
+- token name (or auto-generated identifier)
+- creation date
+- expiration date
+
+**revoke a token**:
+1. go to portal → "your data" → "developer tokens"
+2. find the token in the list
+3. click "revoke" to immediately invalidate it
+
+**via API**:
+```bash
+# list tokens
+curl -H "Authorization: Bearer $PLYR_TOKEN" https://api.plyr.fm/auth/developer-tokens
+
+# revoke by prefix (first 8 chars shown in list)
+curl -X DELETE -H "Authorization: Bearer $PLYR_TOKEN" https://api.plyr.fm/auth/developer-tokens/abc12345
+```
+
+### using tokens
+
+set the token in your environment:
+```bash
+export PLYR_TOKEN="your_token_here"
+```
+
+use with any authenticated endpoint:
+```bash
+# check auth
+curl -H "Authorization: Bearer $PLYR_TOKEN" https://api.plyr.fm/auth/me
+```
+
+**CLI usage** (`scripts/plyr.py`):
+```bash
+# list your tracks
+PLYR_API_URL=https://api.plyr.fm uv run scripts/plyr.py list
+
+# upload a track
+PLYR_API_URL=https://api.plyr.fm uv run scripts/plyr.py upload track.mp3 "My Track"
+
+# download a track
+PLYR_API_URL=https://api.plyr.fm uv run scripts/plyr.py download 42 -o my-track.mp3
+
+# delete a track
+PLYR_API_URL=https://api.plyr.fm uv run scripts/plyr.py delete 42 -y
+```
+
+### configuration
+
+backend settings in `AuthSettings`:
+- `developer_token_default_days`: default expiration (90 days)
+- `developer_token_max_days`: max allowed expiration (365 days)
+- use `expires_in_days: 0` for tokens that never expire
+
+### how it works
+
+developer tokens are sessions with their own independent OAuth grant. when you create a dev token, you go through a full OAuth authorization flow at your PDS, which gives the token its own access/refresh credentials. this means:
+- dev tokens can refresh independently (no staleness when browser session refreshes)
+- each token has its own DPoP keypair for request signing
+- logging out of browser doesn't affect dev tokens (cookie isolation)
+- revoking browser session doesn't affect dev tokens
+
+dev tokens can:
+- read your data (tracks, likes, profile)
+- upload tracks (creates ATProto records on your PDS)
+- perform any authenticated action
+
+**security notes**:
+- tokens have full account access - treat like passwords
+- revoke individual tokens via the portal or API
+- each token is independent - revoking one doesn't affect others
+- token names help identify which token is used where
+- tokens require explicit OAuth consent at your PDS
+
 ## references
 
 - [MDN: HttpOnly cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#security)
···
 - PR #239: frontend localStorage removal
 - PR #243: backend cookie implementation
 - PR #244: merged cookie-based auth
+- PR #367: developer tokens with independent OAuth grants

docs/backend/transcoder.md

···
 if needed in the future, add to `src/backend/config.py`:
 
 ```python
-class TranscoderSettings(RelaySettingsSection):
+class TranscoderSettings(AppSettingsSection):
     url: str = Field(
         default="https://plyr-transcoder.fly.dev",
         validation_alias="TRANSCODER_URL"

frontend/src/routes/portal/+page.svelte

···
 	let deleteAtprotoRecords = $state(false);
 	let deleting = $state(false);
 
+	// developer token state
+	let creatingToken = $state(false);
+	let developerToken = $state<string | null>(null);
+	let tokenExpiresDays = $state(90);
+	let tokenName = $state('');
+	let tokenCopied = $state(false);
+
+	// existing tokens list
+	interface TokenInfo {
+		session_id: string;
+		name: string | null;
+		created_at: string;
+		expires_at: string | null;
+	}
+	let existingTokens = $state<TokenInfo[]>([]);
+	let loadingTokens = $state(false);
+	let revokingToken = $state<string | null>(null);
+
 	onMount(async () => {
 		// check if exchange_token is in URL (from OAuth callback)
 		const params = new URLSearchParams(window.location.search);
 		const exchangeToken = params.get('exchange_token');
+		const isDevToken = params.get('dev_token') === 'true';
 
 		if (exchangeToken) {
-			// exchange token for session_id (cookie is set automatically by backend)
+			// exchange token for session_id
 			try {
 				const exchangeResponse = await fetch(`${API_URL}/auth/exchange`, {
 					method: 'POST',
···
 				});
 
 				if (exchangeResponse.ok) {
-					await auth.initialize();
+					const data = await exchangeResponse.json();
+
+					if (isDevToken) {
+						// this is a developer token - display it to the user
+						developerToken = data.session_id;
+						toast.success('developer token created - save it now!');
+					} else {
+						// regular login - initialize auth
+						await auth.initialize();
+					}
 				}
 			} catch (_e) {
 				console.error('failed to exchange token:', _e);
···
 			await loadArtistProfile();
 			await loadMyAlbums();
 			await loadPreferences();
+			await loadDeveloperTokens();
 		} catch (_e) {
 			console.error('error loading portal data:', _e);
 			error = 'failed to load portal data';
···
 			loading = false;
 		}
 	});
+
+	async function loadDeveloperTokens() {
+		loadingTokens = true;
+		try {
+			const response = await fetch(`${API_URL}/auth/developer-tokens`, {
+				credentials: 'include'
+			});
+			if (response.ok) {
+				const data = await response.json();
+				existingTokens = data.tokens;
+			}
+		} catch (_e) {
+			console.error('failed to load developer tokens:', _e);
+		} finally {
+			loadingTokens = false;
+		}
+	}
 
 	async function loadMyTracks() {
 		loadingTracks = true;
···
 		}
 	}
 
+	async function createDeveloperToken() {
+		creatingToken = true;
+		developerToken = null;
+		tokenCopied = false;
+
+		try {
+			// start OAuth flow for dev token - this returns an auth URL
+			const response = await fetch(`${API_URL}/auth/developer-token/start`, {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				credentials: 'include',
+				body: JSON.stringify({
+					name: tokenName || null,
+					expires_in_days: tokenExpiresDays
+				})
+			});
+
+			if (!response.ok) {
+				const error = await response.json();
+				toast.error(error.detail || 'failed to start token creation');
+				creatingToken = false;
+				return;
+			}
+
+			const result = await response.json();
+			tokenName = ''; // clear the name field
+
+			// redirect to PDS for authorization
+			// on callback, user will return with dev_token=true and the token will be displayed
+			window.location.href = result.auth_url;
+		} catch (e) {
+			console.error('failed to create token:', e);
+			toast.error('failed to create token');
+			creatingToken = false;
+		}
+		// note: we don't set creatingToken = false here because we're redirecting
+	}
+
+	async function revokeToken(tokenId: string, name: string | null) {
+		if (!confirm(`revoke token "${name || tokenId}"?`)) return;
+
+		revokingToken = tokenId;
+		try {
+			const response = await fetch(`${API_URL}/auth/developer-tokens/${tokenId}`, {
+				method: 'DELETE',
+				credentials: 'include'
+			});
+
+			if (!response.ok) {
+				const error = await response.json();
+				toast.error(error.detail || 'failed to revoke token');
+				return;
+			}
+
+			toast.success('token revoked');
+			await loadDeveloperTokens();
+		} catch (e) {
+			console.error('failed to revoke token:', e);
+			toast.error('failed to revoke token');
+		} finally {
+			revokingToken = null;
+		}
+	}
+
+	async function copyToken() {
+		if (!developerToken) return;
+		try {
+			await navigator.clipboard.writeText(developerToken);
+			tokenCopied = true;
+			toast.success('token copied to clipboard');
+			setTimeout(() => { tokenCopied = false; }, 2000);
+		} catch (e) {
+			console.error('failed to copy:', e);
+			toast.error('failed to copy token');
+		}
+	}
+
 	async function deleteAccount() {
 		if (!auth.user || deleteConfirmText !== auth.user.handle) return;
 
···
 					</button>
 				</div>
 			{/if}
+
+			<div class="data-control developer-section">
+				<div class="control-info">
+					<h3>developer tokens</h3>
+					<p class="control-description">
+						create tokens for programmatic API access (uploads, track management)
+					</p>
+				</div>
+
+				{#if loadingTokens}
+					<p class="loading-tokens">loading tokens...</p>
+				{:else if existingTokens.length > 0}
+					<div class="existing-tokens">
+						<h4 class="tokens-header">active tokens</h4>
+						<div class="tokens-list">
+							{#each existingTokens as token}
+								<div class="token-item">
+									<div class="token-info">
+										<span class="token-name">{token.name || `token_${token.session_id}`}</span>
+										<span class="token-meta">
+											created {new Date(token.created_at).toLocaleDateString()}
+											{#if token.expires_at}
+												· expires {new Date(token.expires_at).toLocaleDateString()}
+											{:else}
+												· never expires
+											{/if}
+										</span>
+									</div>
+									<button
+										class="revoke-btn"
+										onclick={() => revokeToken(token.session_id, token.name)}
+										disabled={revokingToken === token.session_id}
+										title="revoke token"
+									>
+										{revokingToken === token.session_id ? '...' : 'revoke'}
+									</button>
+								</div>
+							{/each}
+						</div>
+					</div>
+				{/if}
+
+				{#if developerToken}
+					<div class="token-display">
+						<code class="token-value">{developerToken}</code>
+						<button
+							class="copy-btn"
+							onclick={copyToken}
+							title="copy token"
+						>
+							{tokenCopied ? '✓' : 'copy'}
+						</button>
+						<button
+							class="dismiss-btn"
+							onclick={() => developerToken = null}
+							title="dismiss"
+						>
+							✕
+						</button>
+					</div>
+					<p class="token-warning">
+						save this token now - you won't be able to see it again
+					</p>
+				{:else}
+					<div class="token-form">
+						<input
+							type="text"
+							class="token-name-input"
+							bind:value={tokenName}
+							placeholder="token name (optional)"
+							disabled={creatingToken}
+						/>
+						<label class="expires-label">
+							<span>expires in</span>
+							<select bind:value={tokenExpiresDays} class="expires-select">
+								<option value={30}>30 days</option>
+								<option value={90}>90 days</option>
+								<option value={180}>180 days</option>
+								<option value={365}>1 year</option>
+								<option value={0}>never</option>
+							</select>
+						</label>
+						<button
+							class="create-token-btn"
+							onclick={createDeveloperToken}
+							disabled={creatingToken}
+						>
+							{creatingToken ? 'creating...' : 'create token'}
+						</button>
+					</div>
+				{/if}
+			</div>
 
 			<div class="data-control danger-zone">
 				<div class="control-info">
···
 		font-size: 0.85rem;
 		color: #888;
 		min-width: 60px;
+	}
+
+	/* developer token section */
+	.developer-section {
+		flex-direction: column;
+		align-items: stretch;
+		gap: 1rem;
+	}
+
+	.developer-section .control-info h3 {
+		color: var(--accent);
+	}
+
+	.token-form {
+		display: flex;
+		align-items: center;
+		gap: 1rem;
+		flex-wrap: wrap;
+	}
+
+	.expires-label {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		font-size: 0.9rem;
+		color: #888;
+	}
+
+	.expires-select {
+		padding: 0.5rem 0.75rem;
+		background: #0a0a0a;
+		border: 1px solid #333;
+		border-radius: 4px;
+		color: white;
+		font-size: 0.9rem;
+		font-family: inherit;
+		cursor: pointer;
+	}
+
+	.expires-select:focus {
+		outline: none;
+		border-color: var(--accent);
+	}
+
+	.create-token-btn {
+		padding: 0.6rem 1.25rem;
+		background: var(--accent);
+		color: white;
+		border: none;
+		border-radius: 6px;
+		font-size: 0.9rem;
+		font-weight: 600;
+		cursor: pointer;
+		transition: all 0.2s;
+		white-space: nowrap;
+		width: auto;
+	}
+
+	.create-token-btn:hover:not(:disabled) {
+		filter: brightness(1.1);
+		transform: translateY(-1px);
+	}
+
+	.create-token-btn:disabled {
+		opacity: 0.5;
+		cursor: not-allowed;
+		transform: none;
+	}
+
+	.token-display {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		background: #0a0a0a;
+		border: 1px solid #333;
+		border-radius: 6px;
+		padding: 0.75rem;
+		overflow: hidden;
+	}
+
+	.token-value {
+		flex: 1;
+		font-family: monospace;
+		font-size: 0.85rem;
+		color: #5ce87b;
+		word-break: break-all;
+		user-select: all;
+	}
+
+	.copy-btn,
+	.dismiss-btn {
+		padding: 0.4rem 0.75rem;
+		background: #2a2a2a;
+		border: 1px solid #3a3a3a;
+		border-radius: 4px;
+		color: #888;
+		font-size: 0.85rem;
+		cursor: pointer;
+		transition: all 0.2s;
+		width: auto;
+	}
+
+	.copy-btn:hover {
+		background: #3a3a3a;
+		border-color: var(--accent);
+		color: var(--accent);
+	}
+
+	.dismiss-btn:hover {
+		background: #3a3a3a;
+		border-color: #666;
+		color: #aaa;
+	}
+
+	.token-warning {
+		font-size: 0.85rem;
+		color: #e9a545;
+		margin: 0;
+	}
+
+	/* existing tokens list */
+	.existing-tokens {
+		width: 100%;
+		margin-bottom: 1rem;
+	}
+
+	.tokens-header {
+		font-size: 0.9rem;
+		font-weight: 600;
+		color: #888;
+		margin: 0 0 0.75rem 0;
+	}
+
+	.tokens-list {
+		display: flex;
+		flex-direction: column;
+		gap: 0.5rem;
+	}
+
+	.token-item {
+		display: flex;
+		justify-content: space-between;
+		align-items: center;
+		gap: 1rem;
+		padding: 0.75rem;
+		background: #0a0a0a;
+		border: 1px solid #2a2a2a;
+		border-radius: 6px;
+	}
+
+	.token-info {
+		display: flex;
+		flex-direction: column;
+		gap: 0.25rem;
+		min-width: 0;
+		flex: 1;
+	}
+
+	.token-name {
+		font-family: monospace;
+		font-size: 0.9rem;
+		color: #e8e8e8;
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+	}
+
+	.token-meta {
+		font-size: 0.8rem;
+		color: #666;
+	}
+
+	.revoke-btn {
+		padding: 0.4rem 0.75rem;
+		background: transparent;
+		border: 1px solid #4a2020;
+		border-radius: 4px;
+		color: #ff6b6b;
+		font-size: 0.85rem;
+		cursor: pointer;
+		transition: all 0.2s;
+		width: auto;
+		flex-shrink: 0;
+	}
+
+	.revoke-btn:hover:not(:disabled) {
+		background: rgba(255, 107, 107, 0.1);
+		border-color: #ff6b6b;
+	}
+
+	.revoke-btn:disabled {
+		opacity: 0.5;
+		cursor: not-allowed;
+	}
+
+	.token-name-input {
+		padding: 0.5rem 0.75rem;
+		background: #0a0a0a;
+		border: 1px solid #333;
+		border-radius: 4px;
+		color: white;
+		font-size: 0.9rem;
+		font-family: inherit;
+		min-width: 150px;
+	}
+
+	.token-name-input:focus {
+		outline: none;
+		border-color: var(--accent);
+	}
+
+	.token-name-input:disabled {
+		opacity: 0.5;
+		cursor: not-allowed;
+	}
+
+	.loading-tokens {
+		font-size: 0.9rem;
+		color: #666;
+		margin: 0;
 	}
 </style>

scripts/plyr.py

···
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = [
+#     "cyclopts>=3.0",
+#     "httpx>=0.27",
+#     "pydantic-settings>=2.0",
+#     "rich>=13.0",
+# ]
+# ///
+"""
+plyr.fm CLI - upload and download tracks programmatically.
+
+setup:
+    1. create a developer token at plyr.fm/portal -> "your data" -> "developer tokens"
+    2. export PLYR_TOKEN="your_token_here"
+
+usage:
+    uv run scripts/plyr.py list
+    uv run scripts/plyr.py upload track.mp3 "My Track" --album "My Album"
+    uv run scripts/plyr.py download 42 -o my-track.mp3
+    uv run scripts/plyr.py delete 42
+
+environments (defaults to localhost:8001):
+    PLYR_API_URL=https://api-stg.plyr.fm uv run scripts/plyr.py list  # staging
+    PLYR_API_URL=https://api.plyr.fm uv run scripts/plyr.py list      # production
+"""
+
+import json
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import httpx
+from cyclopts import App, Parameter
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+class Settings(BaseSettings):
+    """plyr.fm CLI configuration.
+
+    override api_url for different environments:
+        PLYR_API_URL=http://localhost:8001    # local dev (default)
+        PLYR_API_URL=https://api-stg.plyr.fm  # staging
+        PLYR_API_URL=https://api.plyr.fm      # production
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="PLYR_", env_file=".env", extra="ignore"
+    )
+
+    token: str | None = Field(default=None, description="API token")
+    api_url: str = Field(default="http://localhost:8001", description="API base URL")
+
+    @property
+    def headers(self) -> dict[str, str]:
+        if not self.token:
+            console.print("[red]error:[/] PLYR_TOKEN not set")
+            console.print("create a token at plyr.fm/portal -> 'developer tokens'")
+            sys.exit(1)
+        return {"Authorization": f"Bearer {self.token}"}
+
+
+settings = Settings()
+app = App(help="plyr.fm CLI - upload and download tracks")
+
+
[e-mail]
+def upload(
+    file: Annotated[Path, Parameter(help="audio file to upload")],
+    title: Annotated[str, Parameter(help="track title")],
+    album: Annotated[str | None, Parameter(help="album name")] = None,
+) -> None:
+    """upload a track to plyr.fm."""
+    if not file.exists():
+        console.print(f"[red]error:[/] file not found: {file}")
+        sys.exit(1)
+
+    with console.status("uploading..."):
+        with open(file, "rb") as f:
+            files = {"file": (file.name, f)}
+            data = {"title": title}
+            if album:
+                data["album"] = album
+
+            response = httpx.post(
+                f"{settings.api_url}/tracks/",
+                headers=settings.headers,
+                files=files,
+                data=data,
+                timeout=120.0,
+            )
+
+    if response.status_code == 401:
+        console.print("[red]error:[/] invalid or expired token")
+        sys.exit(1)
+
+    if response.status_code == 403:
+        detail = response.json().get("detail", "")
+        if "artist_profile_required" in detail:
+            console.print("[red]error:[/] create an artist profile first at plyr.fm")
+        elif "scope_upgrade_required" in detail:
+            console.print("[red]error:[/] log out and back in, then create a new token")
+        else:
+            console.print(f"[red]error:[/] forbidden - {detail}")
+        sys.exit(1)
+
+    response.raise_for_status()
+    upload_data = response.json()
+    upload_id = upload_data.get("upload_id")
+
+    if not upload_id:
+        console.print(f"[green]done:[/] {response.json()}")
+        return
+
+    # poll for completion
+    console.print(f"processing: {upload_id}")
+    with httpx.stream(
+        "GET",
+        f"{settings.api_url}/tracks/uploads/{upload_id}/progress",
+        headers=settings.headers,
+        timeout=300.0,
+    ) as sse:
+        for line in sse.iter_lines():
+            if line.startswith("data: "):
+                data = json.loads(line[6:])
+                status = data.get("status")
+
+                if status == "completed":
+                    track_id = data.get("track_id")
+                    console.print(f"[green]uploaded:[/] track {track_id}")
+                    return
+                elif status == "failed":
+                    error = data.get("error", "unknown error")
+                    console.print(f"[red]failed:[/] {error}")
+                    sys.exit(1)
+
+
[e-mail]
+def download(
+    track_id: Annotated[int, Parameter(help="track ID to download")],
+    output: Annotated[
+        Path | None, Parameter(name=["--output", "-o"], help="output file")
+    ] = None,
+) -> None:
+    """download a track from plyr.fm."""
+    # get track info first
+    with console.status("fetching track info..."):
+        info_response = httpx.get(
+            f"{settings.api_url}/tracks/{track_id}",
+            headers=settings.headers,
+            timeout=30.0,
+        )
+
+    if info_response.status_code == 404:
+        console.print(f"[red]error:[/] track {track_id} not found")
+        sys.exit(1)
+
+    info_response.raise_for_status()
+    track = info_response.json()
+
+    # determine output filename
+    if output is None:
+        # use track title + extension from file_type
+        ext = track.get("file_type", "mp3")
+        safe_title = "".join(
+            c if c.isalnum() or c in " -_" else "" for c in track["title"]
+        )
+        output = Path(f"{safe_title}.{ext}")
+
+    # download audio
+    with console.status(f"downloading {track['title']}..."):
+        audio_response = httpx.get(
+            f"{settings.api_url}/audio/{track['file_id']}",
+            headers=settings.headers,
+            follow_redirects=True,
+            timeout=300.0,
+        )
+
+    audio_response.raise_for_status()
+
+    output.write_bytes(audio_response.content)
+    size_mb = len(audio_response.content) / 1024 / 1024
+    console.print(f"[green]saved:[/] {output} ({size_mb:.1f} MB)")
+
+
[e-mail](name="list")
+def list_tracks(
+    limit: Annotated[int, Parameter(help="max tracks to show")] = 20,
+) -> None:
+    """list your tracks."""
+    with console.status("fetching tracks..."):
+        response = httpx.get(
+            f"{settings.api_url}/tracks/",
+            headers=settings.headers,
+            timeout=30.0,
+        )
+
+    response.raise_for_status()
+    tracks = response.json().get("tracks", [])
+
+    if not tracks:
+        console.print("no tracks found")
+        return
+
+    table = Table(title="your tracks")
+    table.add_column("ID", style="cyan")
+    table.add_column("title")
+    table.add_column("album")
+    table.add_column("plays", justify="right")
+
+    for track in tracks[:limit]:
+        album = track.get("album")
+        album_name = album.get("title") if isinstance(album, dict) else (album or "-")
+        table.add_row(
+            str(track["id"]),
+            track["title"],
+            album_name,
+            str(track.get("play_count", 0)),
+        )
+
+    console.print(table)
+
+
[e-mail]
+def delete(
+    track_id: Annotated[int, Parameter(help="track ID to delete")],
+    yes: Annotated[
+        bool, Parameter(name=["--yes", "-y"], help="skip confirmation")
+    ] = False,
+) -> None:
+    """delete a track."""
+    # get track info first
+    with console.status("fetching track info..."):
+        info_response = httpx.get(
+            f"{settings.api_url}/tracks/{track_id}",
+            headers=settings.headers,
+            timeout=30.0,
+        )
+
+    if info_response.status_code == 404:
+        console.print(f"[red]error:[/] track {track_id} not found")
+        sys.exit(1)
+
+    info_response.raise_for_status()
+    track = info_response.json()
+
+    if not yes:
+        console.print(f"delete '{track['title']}'? [y/N] ", end="")
+        if input().lower() != "y":
+            console.print("cancelled")
+            return
+
+    response = httpx.delete(
+        f"{settings.api_url}/tracks/{track_id}",
+        headers=settings.headers,
+        timeout=30.0,
+    )
+
+    if response.status_code == 404:
+        console.print(f"[red]error:[/] track {track_id} not found")
+        sys.exit(1)
+
+    response.raise_for_status()
+    console.print(f"[green]deleted:[/] {track['title']}")
+
+
+if __name__ == "__main__":
+    app()