Authentication
Public data is open. To change anything, send an API key that acts on behalf of your JilTV account.
API keys
- Sign in on JilTV and open Developers.
- Create an app for your integration, then a key inside it.
- Pick only the scopes the integration needs and, ideally, an expiry.
- Copy the key. It starts with
jtv_and is shown exactly once.
Send it as a bearer token:
curl https://api.jiltv.app/v1/graphql \
-H "Authorization: Bearer $JILTV_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"query":"{ viewer { authMethod scopes user { username } } }"}'Keep keys server-side
A key can change your emotes and sets. Store it in an environment variable or secret manager, never in a browser extension, frontend
bundle or public repository. If a key leaks, revoke it on the Developers page; it stops working within a minute.
Scopes
A key without scopes is read-only, which is useful to identify your integration and get its own rate limit bucket.
| Scope | Allows |
|---|
Scopes narrow what a key may do; they never widen what your account may do. A key with SETS_WRITE still can't edit
someone else's set unless you are an editor of that channel.
What keys can never do
- Moderation and admin actions. Fields marked staff in the reference reject API keys, even a moderator's.
- Manage API keys. Creating or revoking keys needs a signed-in website session, so a leaked key can't mint new ones.
Checking a key
viewer returns who you are, authMethod (API_KEY or SESSION) and the granted scopes. It is null without credentials. An invalid, expired or revoked key fails the whole request with HTTP 401 and code invalid_api_key, so mistakes never silently fall back to anonymous access.
Security notes
- Keys are stored as SHA-256 hashes; JilTV can't show a key again, only its prefix.
- Bearer requests don't use cookies, so they're not subject to CSRF and work from any server.
- If the account owning a key is banned, all its keys stop working.