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

# Hitorino API Authentication — API Keys and Bearer Tokens

> Generate a Hitorino API key, attach it as a Bearer token on every request, understand read/write token scopes, and handle 401 and 403 auth error codes.

Every request to the Hitorino API must be authenticated with an API key — except for a small set of public read endpoints that fall back to unauthenticated rate limits. You generate API keys directly from the Hitorino dashboard and pass them as a Bearer token in the `Authorization` header of each request.

## Generating an API Key

To create an API key, open the Hitorino dashboard and navigate to **Settings → API Keys**. Click **New API Key**, give it a descriptive name (for example, `production-backend` or `analytics-service`), select the appropriate scope, and click **Create**. The key is displayed exactly once — copy it immediately and store it in a secure secrets manager or environment variable. Hitorino does not store or display the full key after creation.

<Warning>
  If you close the key-creation dialog without copying the key, you must delete that key and generate a new one. There is no way to retrieve the plaintext value later.
</Warning>

You can create multiple API keys — one per integration or environment — and revoke them individually from the same **Settings → API Keys** page. Revoking a key immediately invalidates it; all subsequent requests using that key receive a `401` response.

## Sending the API Key

Include your API key in the `Authorization` header using the `Bearer` scheme on every authenticated request:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Note>
  Replace `YOUR_API_KEY` with the actual key value you copied from the dashboard. Do not include the literal string `Bearer` twice or wrap the key in quotes within the header value.
</Note>

### Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.hitorino.tv/v1/streams \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript (fetch) theme={null}
  const response = await fetch('https://api.hitorino.tv/v1/streams', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python (requests) theme={null}
  import requests

  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
  }

  response = requests.get('https://api.hitorino.tv/v1/streams', headers=headers)
  data = response.json()
  print(data)
  ```
</CodeGroup>

## Token Scopes

When you create an API key, you assign it one of two scopes. Choosing the narrowest scope your integration needs reduces the blast radius if the key is ever compromised.

| Scope   | Access                                                                                                                                          |
| ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `read`  | `GET` requests only. Can list and retrieve streams, videos, users, and webhooks, but cannot create, update, or delete resources.                |
| `write` | Full access to all endpoints, including `POST` and `DELETE` operations such as scheduling streams, registering webhooks, and deleting webhooks. |

<Tip>
  Use a `read`-scoped key for analytics dashboards, content syndication pipelines, and any integration that only needs to consume data. Reserve `write`-scoped keys for backend services that actively create or manage resources on Hitorino.
</Tip>

If a `read`-scoped key attempts a write operation, the API returns a `403 Forbidden` error with the code `insufficient_scope`.

## Authentication Error Codes

The following error responses relate specifically to authentication and authorization failures:

### 401 Unauthorized

The API returns `401` when no API key is provided or the key is invalid (for example, it has been revoked or was typed incorrectly).

```json theme={null}
{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is missing or invalid."
  }
}
```

**Common causes:**

* The `Authorization` header is absent from the request.
* The key value is incorrect or contains extra whitespace.
* The key was revoked from the Hitorino dashboard.

### 403 Forbidden

The API returns `403` when the API key is valid but lacks the scope required by the endpoint being called.

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have write access. Generate a write-scoped key in Settings → API Keys."
  }
}
```

**Common causes:**

* A `read`-scoped key is used to call a `POST` or `DELETE` endpoint.
* The key is valid but belongs to an account that does not have access to the requested resource.

## Security Best Practices

* **Never hard-code API keys** in source code, front-end JavaScript bundles, or mobile app binaries. Use environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault, Doppler).
* **Rotate keys periodically.** Create a new key, update your integration, verify it works, then revoke the old key.
* **Use one key per environment.** Keep separate keys for development, staging, and production so you can revoke a compromised environment's key without affecting others.
* **Log key usage.** The Hitorino dashboard shows last-used timestamps for each key, making it easy to spot unexpected activity.