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

# Swytcho API Authentication: Keys, Scopes & Security

> Learn how to generate API keys, pass them as Bearer tokens, apply the right scopes, and follow security best practices to keep your integration safe.

Swytcho authenticates every API request using an API key passed as a **Bearer token** in the `Authorization` header. There are no session cookies or OAuth flows to set up — every call is stateless, and your key is the only credential you need. This makes Swytcho straightforward to integrate from any language, framework, or HTTP client.

## Get an API key

API keys are managed from the Swytcho dashboard. Follow these steps to create one:

<Steps>
  <Step title="Open the API Keys page">
    Log in to your account at [swytcho.com](https://swytcho.com), then click **API Keys** in the left navigation sidebar.
  </Step>

  <Step title="Create a new key">
    Click **Create new key**. Enter a descriptive name that helps you identify where the key is used — for example, `production-backend` or `local-dev`. Select the appropriate scope (see [API key scopes](#api-key-scopes) below), then click **Create**.
  </Step>

  <Step title="Copy and store the key">
    Your key is displayed exactly once. Copy it immediately and save it to a secure location such as a secrets manager or an environment variable in your deployment environment. If you lose the key, you'll need to generate a new one.
  </Step>
</Steps>

## Use your API key in requests

Include your API key in the `Authorization` header of every request using the `Bearer` scheme. The examples below show how to do this in curl, Python, and Node.js.

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.swytcho.com/v1/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "swytcho-1",
      "messages": [
        { "role": "user", "content": "Hello!" }
      ]
    }'
  ```

  ```python Python theme={null}
  import os
  import requests

  headers = {
      "Authorization": f"Bearer {os.environ['SWYTCHO_API_KEY']}",
      "Content-Type": "application/json",
  }

  response = requests.post(
      "https://api.swytcho.com/v1/chat/completions",
      headers=headers,
      json={
          "model": "swytcho-1",
          "messages": [{"role": "user", "content": "Hello!"}],
      },
  )

  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://api.swytcho.com/v1/chat/completions", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.SWYTCHO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "swytcho-1",
      messages: [{ role: "user", content: "Hello!" }],
    }),
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Security best practices

<Warning>
  Treat your API key like a password. Anyone who holds your key can make requests billed to your account and access any resource the key's scope permits. If you suspect a key has been exposed, revoke it immediately from the dashboard and issue a new one.
</Warning>

<Note>
  **Never hardcode API keys in your source code.** Instead, load them at runtime from environment variables or a secrets manager:

  * Set `SWYTCHO_API_KEY` in your shell, `.env` file, or your hosting platform's environment variable settings.
  * Use a tool like [dotenv](https://github.com/motdotla/dotenv) (Node.js) or [python-dotenv](https://github.com/theskumar/python-dotenv) (Python) to load the variable locally.
  * Add `.env` to your `.gitignore` so the file is never committed to version control.
  * Rotate keys regularly and revoke any key that is no longer in active use.
</Note>

## API key scopes

When you create a key, you assign it one of two scopes that control what it can do:

| Scope            | Description                                                                                                                                                       |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Read**         | Allows read-only operations such as listing available models and retrieving usage statistics. Use this scope for monitoring dashboards or analytics integrations. |
| **Read / Write** | Allows all API operations including chat completions, embeddings, and function calling. Use this scope for any key that drives active inference workloads.        |

Grant the minimum scope a key needs for its purpose. If a read-only key is compromised, no inference costs can be incurred.

## Handling authentication failures

If a request cannot be authenticated, the API returns a `401 Unauthorized` response. This happens when the key is missing, malformed, revoked, or passed in the wrong header.

```json theme={null}
{
  "error": {
    "message": "Invalid API key provided. Check your key and try again.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

When you receive a `401`, verify the following:

1. The `Authorization` header is present and formatted as `Bearer YOUR_API_KEY` (note the space after `Bearer`).
2. The key hasn't been revoked — check the **API Keys** page in the dashboard.
3. You're targeting the correct base URL: `https://api.swytcho.com/v1`.

<Info>
  A `403 Forbidden` response means your key is valid but lacks the scope required for the requested operation. Regenerate the key with the correct scope, or contact support if you believe the scope assignment is incorrect.
</Info>