Getting Started

Authentication

All API requests require authentication via a proxy key. Proxy keys scope access to specific providers, models, and organizations.

Bearer Token

Include your proxy key as a Bearer token in the Authorization header of every request.

Proxy keys start with mql_ and are scoped to your account or organization.

Keep keys secret

Never expose proxy keys in client-side code or public repositories. Use environment variables or a secrets manager.

Request Header

Authorization: Bearer mql_your_proxy_key_here

SDK Authentication

With the SDK, pass your key during initialization. All subsequent calls are automatically authenticated.

TypeScript SDK

import Metriqual from '@metriqual/sdk';

const mql = new Metriqual({
  apiKey: process.env.MQL_API_KEY!,
  baseUrl: 'https://api.metriqual.com'
});

Python SDK

from metriqual import MQL

mql = MQL(api_key="mql_your_proxy_key")

# Or use an environment variable (recommended)
# export MQL_API_KEY=mql_your_proxy_key
mql = MQL()  # reads MQL_API_KEY from env

CLI Authentication

Authenticate the CLI by logging in with your Metriqual account. Your credentials are stored locally for subsequent commands.

CLI

# Interactive login
mql auth login

# Check current auth status
mql auth status

# Logout
mql auth logout

Creating Proxy Keys

POST/v1/proxy-keys

Create proxy keys programmatically via the API. Keys can be scoped to specific providers, models, and have time-based validity.

Body Parameters

namestringrequired

A descriptive name for the key

provider_keysobjectbodyrequired

Map of provider name to API key (e.g. {"openai": "sk-..."})

allowed_modelsstring[]

List of model IDs this key can access. Empty = all models.

valid_fromstring

ISO 8601 start date for key validity

valid_untilstring

ISO 8601 expiry date for key validity

cURL

curl -X POST https://api.metriqual.com/v1/proxy-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-key",
    "provider_keys": {
      "openai": "sk-your-openai-key"
    },
    "allowed_models": ["gpt-4o", "gpt-4o-mini"]
  }'

200

{
  "proxy_key": "mql_abc123def456",
  "name": "production-key",
  "is_active": true,
  "created_at": "2025-01-15T10:30:00Z"
}

Organization Keys

For team usage, create organization-scoped proxy keys. These require the x-org-id header on authenticated requests.

Organization-scoped request

curl https://api.metriqual.com/v1/chat/completions \
  -H "Authorization: Bearer mql_org_key_here" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hi"}]}'

Error Responses

Authentication failures return standard error objects:

401

{"error": "Invalid proxy key"}

403

{"error": "Proxy key has been deactivated"}

403

{"error": "Proxy key has expired. Valid until: 2025-01-01 00:00:00 UTC"}

Quick Start