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

# Authenticate with Portrix: API Keys and Best Practices

> Learn how to create and manage API keys for Portrix. Send your key as a Bearer token in the Authorization header on every request.

Portrix uses API key authentication. Every request you send to the Portrix API must include your API key as a Bearer token in the `Authorization` header. There are no session tokens, OAuth flows, or per-provider credentials to manage — one Portrix key grants access to every model in the catalog.

## Getting your API key

<Steps>
  <Step title="Open the Portrix dashboard">
    Go to [app.portrix.ai](https://app.portrix.ai) and sign in to your account. If you don't have an account yet, sign up for free — it only takes a minute.
  </Step>

  <Step title="Navigate to API Keys">
    In the left sidebar, click **Settings**, then select **API Keys**.
  </Step>

  <Step title="Create a new key">
    Click **Create new key**. Enter a descriptive label so you can identify the key later — for example, `production`, `staging`, or `local-dev`. Then click **Create**.
  </Step>

  <Step title="Copy and store your key">
    Copy the key shown on screen and store it immediately in a password manager or secrets vault.
  </Step>
</Steps>

<Warning>
  Your API key is displayed only once, immediately after creation. If you close the dialog without copying it, you'll need to revoke the key and create a new one. Store it somewhere safe right away.
</Warning>

## Using your API key

Include your API key in the `Authorization` header of every request using the `Bearer` scheme.

<CodeGroup>
  ```http HTTP theme={null}
  POST https://api.portrix.ai/v1/chat/completions
  Authorization: Bearer YOUR_PORTRIX_API_KEY
  Content-Type: application/json

  {
    "model": "openai/gpt-4o",
    "messages": [{ "role": "user", "content": "Hello!" }]
  }
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="YOUR_PORTRIX_API_KEY",
      base_url="https://api.portrix.ai/v1",
  )

  response = client.chat.completions.create(
      model="openai/gpt-4o",
      messages=[{"role": "user", "content": "Hello!"}],
  )
  print(response.choices[0].message.content)
  ```

  ```typescript Node.js / TypeScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "YOUR_PORTRIX_API_KEY",
    baseURL: "https://api.portrix.ai/v1",
  });

  const response = await client.chat.completions.create({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "Hello!" }],
  });

  console.log(response.choices[0].message.content);
  ```

  ```bash cURL theme={null}
  curl https://api.portrix.ai/v1/chat/completions \
    -H "Authorization: Bearer YOUR_PORTRIX_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai/gpt-4o",
      "messages": [{"role": "user", "content": "Hello!"}]
    }'
  ```
</CodeGroup>

## Portrix request headers

In addition to the `Authorization` header, Portrix accepts several optional headers that give you per-request control over routing and model selection.

| Header               | Description                                                                                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `x-portrix-model`    | Override the model for this request without changing the `model` field in the request body. Useful when you want to centralise model selection at the gateway level.             |
| `x-portrix-fallback` | Specify a fallback model (in `provider/model-name` format) to use if the primary model is unavailable or returns an error. Example: `anthropic/claude-3-5-sonnet`.               |
| `x-portrix-route`    | Control the routing strategy for this request. Accepted values depend on your plan — see the [API Reference](/api-reference/overview) for the full list of supported strategies. |

These headers are optional. When omitted, Portrix uses the `model` field from the request body and applies your account's default routing policy.

```http theme={null}
POST https://api.portrix.ai/v1/chat/completions
Authorization: Bearer YOUR_PORTRIX_API_KEY
Content-Type: application/json
x-portrix-fallback: anthropic/claude-3-5-sonnet
x-portrix-route: latency

{
  "model": "openai/gpt-4o",
  "messages": [{ "role": "user", "content": "Hello!" }]
}
```

## Environment variables

Hard-coding API keys in source code is a security risk. Instead, store your key in an environment variable and read it at runtime.

Set the variable in your shell or in a `.env` file:

<CodeGroup>
  ```bash Shell theme={null}
  export PORTRIX_API_KEY="YOUR_PORTRIX_API_KEY"
  ```

  ```bash .env file theme={null}
  PORTRIX_API_KEY=YOUR_PORTRIX_API_KEY
  ```
</CodeGroup>

Then load the variable in your application:

<CodeGroup>
  ```python Python theme={null}
  import os
  from openai import OpenAI

  client = OpenAI(
      api_key=os.environ["PORTRIX_API_KEY"],
      base_url="https://api.portrix.ai/v1",
  )
  ```

  ```typescript Node.js / TypeScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: process.env.PORTRIX_API_KEY,
    baseURL: "https://api.portrix.ai/v1",
  });
  ```
</CodeGroup>

## Key management

You can create, rename, and revoke API keys at any time from **Settings → API Keys** in the [Portrix dashboard](https://app.portrix.ai).

**Rotating a key** — Create a new key, update your application to use it, verify the new key works, then revoke the old one. There is no downtime if you update the key in your environment before revoking the previous one.

**Naming conventions** — Use clear, environment-scoped names so you can identify which key belongs to which deployment:

| Label         | Purpose                       |
| ------------- | ----------------------------- |
| `production`  | Live customer-facing traffic  |
| `staging`     | Pre-production environment    |
| `development` | Local development and testing |
| `ci`          | Automated test pipelines      |

## Security best practices

* **Never commit API keys to source control.** Add `.env` to your `.gitignore` and use a secrets manager (AWS Secrets Manager, HashiCorp Vault, Doppler, etc.) in production.
* **Use environment variables.** Read the key from `process.env` or `os.environ` rather than inlining it in code.
* **Rotate keys periodically.** Establish a regular rotation schedule — quarterly at minimum — and rotate immediately if you suspect a key has been exposed.
* **Use separate keys per environment.** Isolating keys by environment (production, staging, development) limits the blast radius of an accidental leak and makes auditing easier.

## Error reference

| Status code        | Error                      | Cause                                                                                                                                                |
| ------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | Missing or invalid API key | The `Authorization` header is absent, malformed, or the key does not exist. Check that you're sending `Bearer YOUR_KEY` and that the key is correct. |
| `403 Forbidden`    | Key lacks permissions      | The API key exists but does not have permission to perform the requested action. Check your plan and key scopes in the dashboard.                    |