> ## Documentation Index
> Fetch the complete documentation index at: https://docs.torrin.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to get and use your torrin API key.

Every torrent and store endpoint is authenticated with your instance **API key** — the
same key your Stremio addon and dashboard use. Public `/api/*` endpoints need no auth.

## Get your API key

Your API key is issued when your account is created. On the hosted instance it's shown in
the dashboard; you can also create an account directly:

```bash theme={null}
curl -X POST https://api.torrin.app/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com" }'
```

```json theme={null}
{ "api_key": "YOUR_API_KEY", "email": "you@example.com", "plan": "free" }
```

<Warning>
  Treat the key like a password. Your primary key grants full account access — if it
  leaks, rotate it from the dashboard. For addons, prefer a dedicated **API-only** key
  (below) that can be revoked on its own and can't be used to sign in.
</Warning>

## Use it

Send the key as a bearer token on every authenticated request:

```bash theme={null}
curl https://api.torrin.app/rest/1.0/torrents \
  -H "Authorization: Bearer YOUR_API_KEY"
```

For compatibility, two surfaces also accept alternate forms:

| Surface | Also accepts |
| - | - |
| `/rest/1.0/*` | `?auth_token=YOUR_API_KEY` query parameter |
| `/v0/store/*` | `X-StremThru-Store-Authorization: Bearer YOUR_API_KEY` header |

## Multiple keys & API-only keys

Instead of sharing one key everywhere, you can issue several. Give each addon or
integration its own labelled key, so if one leaks you revoke just that key without
disturbing the others.

Each key is one of:

* **Login-enabled** — full account access (dashboard, billing, credentials, key management).
* **API-only** — can stream, download, and search, but **cannot sign in or change your
  account**. This is the default for new keys and the right choice for an addon: a leaked
  API-only key can't take over your account.

Every key belongs to your account, so all of them are bound to your plan, limits, and expiry.

<Note>Managing keys requires a login-enabled key. API-only keys receive `403` on account routes.</Note>

### List your keys

```bash theme={null}
curl https://api.torrin.app/api/keys \
  -H "Authorization: Bearer YOUR_LOGIN_KEY"
```

```json theme={null}
{ "keys": [
  { "id": "k_123", "label": "AIOStreams", "login_allowed": false,
    "created_at": "2026-08-13T00:00:00Z", "last_used_at": "2026-08-13T12:00:00Z" }
] }
```

### Create a key

```bash theme={null}
curl -X POST https://api.torrin.app/api/keys \
  -H "Authorization: Bearer YOUR_LOGIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "AIOStreams", "login_allowed": false }'
```

```json theme={null}
{ "id": "k_123", "label": "AIOStreams", "key": "YOUR_NEW_KEY", "login_allowed": false }
```

The `key` is returned **once** — store it now. Up to 20 keys per account.

### Revoke a key

```bash theme={null}
curl -X DELETE https://api.torrin.app/api/keys/k_123 \
  -H "Authorization: Bearer YOUR_LOGIN_KEY"
```

The key stops working immediately.

## Errors

| Status | Meaning |
| - | - |
| `401` | Missing or invalid key. |
| `403` | The subscription is paused or expired — resume or renew, then retry. |

<Note>
  Both error shapes differ by surface: `/rest/1.0` returns `{ "error": "...", "error_code": 8 }`,
  and `/v0/store` returns `{ "error": { "code": 401, "message": "..." } }`.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.