Authenticate with Portrix: API Keys and Best Practices

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

Open the Portrix dashboard

Go to 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.

Navigate to API Keys

In the left sidebar, click Settings, then select API Keys.

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.

Copy and store your key

Copy the key shown on screen and store it immediately in a password manager or secrets vault.

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.

Using your API key

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

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!" }]
}

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)

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);

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!"}]
  }'

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 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.

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:

export PORTRIX_API_KEY="YOUR_PORTRIX_API_KEY"

PORTRIX_API_KEY=YOUR_PORTRIX_API_KEY

Then load the variable in your application:

import os
from openai import OpenAI

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

import OpenAI from "openai";

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

Key management

You can create, rename, and revoke API keys at any time from Settings → API Keys in the Portrix dashboard. 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.

Get Started

Core Concepts

Guides

Integrations

Configuration

Help

Authenticate with Portrix: API Keys and Best Practices

Getting your API key

Using your API key

Portrix request headers

Environment variables

Key management

Security best practices

Error reference

​Getting your API key

​Using your API key

​Portrix request headers

​Environment variables

​Key management

​Security best practices

​Error reference

Getting your API key

Using your API key

Portrix request headers

Environment variables

Key management

Security best practices

Error reference