# JellyStreamz auth.md

JellyStreamz exposes product information, release information, public game metadata, and public community requests without authentication. Never ask a person for their Jellyfin server password or JellyStreamz website password to use those read-only resources.

## OAuth discovery

- Authorization server metadata: `https://jellystreamz.com/.well-known/oauth-authorization-server`
- Protected resource metadata: `https://jellystreamz.com/.well-known/oauth-protected-resource`
- Authorization endpoint: `https://jellystreamz.com/oauth/authorize/`
- Token endpoint: `https://jellystreamz.com/oauth/token/`
- Client registration endpoint: `https://jellystreamz.com/oauth/register/`

JellyStreamz uses the OAuth 2.0 Authorization Code flow with PKCE (`S256`). Agent clients must use an exact pre-registered HTTPS redirect URI. Loopback HTTP redirect URIs are allowed for native development clients. Access tokens are opaque bearer credentials and must not be logged or placed in URLs.

## Supported scopes

- `games.read`: Read the public game metadata catalog.
- `community.read`: Read release and public community information.
- `profile.read`: Read the authorizing member's basic JellyStreamz account identity.

Public catalog requests do not require a token. The `profile.read` scope is required for `GET /api/v1/agent/me/`.

## Dynamic client registration

Send JSON to `POST /oauth/register/`:

```json
{
  "client_name": "Example agent",
  "redirect_uris": ["https://agent.example/callback"],
  "scope": "games.read community.read profile.read"
}
```

The response returns a `client_id`. Confidential clients also receive a `client_secret` once. Public clients should omit client authentication and must use PKCE.

## Authorization example

Open the authorization endpoint in the person's browser with `response_type=code`, `client_id`, exact `redirect_uri`, space-delimited `scope`, `state`, `code_challenge`, and `code_challenge_method=S256`. After approval, exchange the one-time code at the token endpoint with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, and `code_verifier`.

## Revocation and support

Access tokens expire and can be revoked by the member. Do not automate contribution, voting, or supporter operations unless a future scope explicitly permits it. Authentication questions can be sent to `hello@jellystreamz.com`.