# Listnr Studio authentication

Agents should obtain credentials for Listnr Studio using the flow below. Public catalog reads do not require a token. Video generation and project writes stay in the authenticated Studio dashboard.

Spec: https://github.com/workos/auth.md

## Discover

Protected-resource metadata lives at https://studio.listnr.ai/.well-known/oauth-protected-resource.
Authorization-server metadata lives at https://studio.listnr.ai/.well-known/oauth-authorization-server.
The `agent_auth.skill` document is this file. The `identity_endpoint` is https://studio.listnr.ai/agent/identity.

A 401 from `/api/v1/videos` includes `WWW-Authenticate: Bearer resource_metadata="https://studio.listnr.ai/.well-known/oauth-protected-resource"`.

## Pick a method

`identity_types_supported`: `anonymous`, `identity_assertion`, `service_auth`.

- **anonymous**: GET `/api/v1/tools`, `/api/v1/pricing`, and `/api/v1/pages` with no Authorization header. Use this for discovery, citations, and plan comparison.
- **identity_assertion**: present an ID-JAG (`urn:ietf:params:oauth:token-type:id-jag`) at `/agent/identity` when an identity provider can mint one for this resource.
- **service_auth**: exchange a registered client at `/api/v1/oauth/token`. Studio does not mint paid-generation tokens on the public host.

## Register

There is no separate partner portal. Create a Listnr account at https://studio.listnr.ai/login and use the same origin. Self-serve signup includes 50 trial credits.

## Claim

POST https://studio.listnr.ai/agent/auth after a successful identity assertion if you are completing an agent_auth claim. Unauthenticated calls return JSON `401` with a resolution hint, not HTML.

## Exchange

POST https://studio.listnr.ai/api/v1/oauth/token with `grant_type=authorization_code` or a documented agent assertion. The public token endpoint returns structured JSON errors. It does not issue generation credentials.

## Use the access_token

Send `Authorization: Bearer <token>` only to write-oriented routes such as `/api/v1/videos`. Catalog GET routes ignore the header. Prefer anonymous reads plus a human handoff to `/create?tool=<toolId>`.

## Errors

API errors are JSON:

```json
{ "error": { "code": "unauthorized", "message": "...", "hint": "..." } }
```

HTML error pages are not used on `/api/v1/*`.

## Revocation

Session cookies issued at `/login` end when the user signs out of Studio. There is no public token-revocation list for anonymous catalog reads because those calls carry no credential.