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

# Authentication

> Configure a Perceptron API key for Python and HTTP requests.

Every API request needs a Perceptron API key. Use a key from the organization that owns the files and other resources your application accesses.

<CardGroup cols={2}>
  <Card title="Create an API key" icon="key" href="https://platform.perceptron.inc/">
    Get your key from the Perceptron platform
  </Card>

  <Card title="Join Discord" icon="discord" href="https://discord.gg/fgBeaACQzE">
    Get help and see what others are building
  </Card>
</CardGroup>

## Set the key in your environment

For Bash or Zsh:

```bash theme={null}
export PERCEPTRON_API_KEY="your-api-key"
```

For Windows PowerShell:

```powershell theme={null}
$env:PERCEPTRON_API_KEY="your-api-key"
```

Start your Python process from that terminal. A notebook or editor that was already running may need its kernel or process restarted to receive the new environment variable.

## Configure the Python client

The Perceptron SDK reads `PERCEPTRON_API_KEY`. You can also pass the key explicitly. Select the Perceptron provider for these guides:

```python theme={null}
import os

from perceptron import Client

client = Client(
    api_key=os.environ["PERCEPTRON_API_KEY"],
    provider="perceptron",
    timeout=60.0,
)
```

Reuse this client for requests with the same credentials. Create a separate client when using another organization's key. The key is read when this code runs; changing the environment later does not update an existing client.

`timeout` is a client setting, not a model parameter. The SDK does not automatically retry requests; its `retries` setting is accepted for compatibility but does not enable retries. See [Error messages](/perceptron-mk1.5/guides/error-messages) before adding a retry policy.

## Authenticate an HTTP request

Direct HTTP requests use the `Authorization` header. For example, list the models:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  https://api.perceptron.inc/v1/models \
  -H "Authorization: Bearer $PERCEPTRON_API_KEY"
```

Do not put the key in the URL, message content, or a media URL. Keep it in a server-side environment or secret store, exclude secret files from source control, and avoid logging authorization headers. Browser and mobile applications should call your backend rather than embed the API key in distributed code.

## Resolve authentication problems

| Symptom                                        | Check                                                                                                                              |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Python raises `KeyError: 'PERCEPTRON_API_KEY'` | Set the variable in the environment of the process running Python. No API request has been made.                                   |
| `401`                                          | Supply a valid, active Perceptron key in the bearer header. Check for copied whitespace or a revoked key.                          |
| `403`                                          | Check the organization's access to the requested resource.                                                                         |
| `429`                                          | Check the error type: rate limiting and exhausted credits need different responses.                                                |
| A request goes to another provider             | Set `provider="perceptron"`, check any configured `base_url` or `PERCEPTRON_BASE_URL`, and pass the Perceptron key to this client. |

For error fields, diagnostic headers, and retry behavior, see [Error messages](/perceptron-mk1.5/guides/error-messages).