Platform

Proxy Keys

Manage proxy keys for accessing the Metriqual gateway. Keys can be scoped to users or organizations with specific provider access.

Proxy Keys vs JWT Tokens

Proxy keys (mql_...) are used to access AI providers through Metriqual. JWT tokens (from Supabase auth) are used to manage your account and keys via the management API.

Create Proxy Key

POST/v1/user/proxy-keys

Body Parameters

namestringrequired

Descriptive name for the key

provider_keysobjectrequired

Map of provider to API key: {"openai": "sk-..."}

allowed_modelsstring[]

Restrict to specific model IDs

valid_fromstring

ISO 8601 start date

valid_untilstring

ISO 8601 expiry date

cURL

curl -X POST https://api.metriqual.com/v1/user/proxy-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-key",
    "provider_keys": {"openai": "sk-..."}
  }'

TypeScript SDK

const key = await mql.proxyKeys.create({
  name: 'dev-key',
  provider_keys: { openai: 'sk-...' }
});
console.log(key.proxy_key); // mql_...

Python SDK

key = mql.proxy_keys.create(
    name="dev-key",
    providers=[{"provider": "openai", "api_key": "sk-..."}]
)
print(key["proxy_key"])  # mql_...

CLI

mql keys create -n "dev-key"
# Interactive prompt for provider keys

mql keys create -n "dev-key" --json

List Proxy Keys

GET/v1/user/proxy-keys

Retrieve all proxy keys for the authenticated user. Returns key metadata (name, created date, providers) but not the full key value.

cURL

curl https://api.metriqual.com/v1/user/proxy-keys \
  -H "Authorization: Bearer YOUR_JWT"

TypeScript SDK

const { keys } = await mql.proxyKeys.list();
keys.forEach(k => console.log(k.name, k.id));

Python SDK

result = mql.proxy_keys.list()
for k in result["keys"]:
    print(k["name"], k["id"])

CLI

mql keys list
mql keys ls --json

Delete Proxy Key

DELETE/v1/user/proxy-keys/:key_id

Permanently delete a proxy key. Any requests using this key will immediately fail.

cURL

curl -X DELETE https://api.metriqual.com/v1/user/proxy-keys/KEY_ID \
  -H "Authorization: Bearer YOUR_JWT"

TypeScript SDK

await mql.proxyKeys.delete('key_id');

Python SDK

mql.proxy_keys.delete("key_id")

CLI

mql keys delete KEY_ID
mql keys rm KEY_ID -y  # skip confirmation

Regenerate Proxy Key

POST/v1/user/proxy-keys/:key_id/regenerate

Regenerate the proxy key value. The old key is immediately invalidated and a new mql_ key is returned.

cURL

curl -X POST https://api.metriqual.com/v1/user/proxy-keys/KEY_ID/regenerate \
  -H "Authorization: Bearer YOUR_JWT"

TypeScript SDK

const result = await mql.proxyKeys.regenerate('key_id');
console.log(result.proxy_key); // new mql_...

Python SDK

result = mql.proxy_keys.regenerate("key_id")
print(result["proxy_key"])  # new mql_...

CLI

mql keys regenerate KEY_ID
mql keys regenerate KEY_ID --json

Get Key Usage

GET/v1/user/proxy-keys/:key_id/usage

View usage statistics for a specific proxy key including request counts, token usage, and cost estimates.

cURL

curl https://api.metriqual.com/v1/user/proxy-keys/KEY_ID/usage \
  -H "Authorization: Bearer YOUR_JWT"

TypeScript SDK

const usage = await mql.proxyKeys.getUsage('key_id');
console.log(usage.total_requests, usage.total_cost);

Python SDK

usage = mql.proxy_keys.get_usage("key_id")
print(usage["total_requests"], usage["total_cost"])

CLI

mql keys usage KEY_ID
mql keys analytics KEY_ID --from 2024-01-01

Test Proxy Key

POST/v1/user/proxy-keys/:key_id/test

Send a test request through a proxy key to verify provider connectivity and configuration.

TypeScript SDK

const result = await mql.proxyKeys.test('key_id', {
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'Hello' }]
});
console.log(result.choices[0].message.content);

Python SDK

result = mql.proxy_keys.test(
    "key_id",
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello"}]
)
print(result["choices"][0]["message"]["content"])

Organization Proxy Keys

Manage proxy keys at the organization level. Shared keys allow team members to use a common key with shared provider access.

GET/v1/organizations/:org_id/proxy-keys

POST/v1/organizations/:org_id/proxy-keys

DELETE/v1/organizations/:org_id/proxy-keys/:key_id

POST/v1/organizations/:org_id/proxy-keys/:key_id/regenerate

TypeScript SDK

// List org keys
const { keys } = await mql.proxyKeys.listForOrg('org_id');

// Create org key
const key = await mql.proxyKeys.createForOrg('org_id', {
  name: 'team-key',
  provider_keys: { openai: 'sk-...' }
});

// Delete org key
await mql.proxyKeys.deleteForOrg('org_id', 'key_id');

// Regenerate org key
const regen = await mql.proxyKeys.regenerateForOrg('org_id', 'key_id');

Python SDK

# List org keys
result = mql.proxy_keys.list_for_org("org_id")

# Create org key
key = mql.proxy_keys.create_for_org(
    "org_id",
    name="team-key",
    providers=[{"provider": "openai", "api_key": "sk-..."}]
)

# Delete org key
mql.proxy_keys.delete_for_org("org_id", "key_id")

# Regenerate org key
regen = mql.proxy_keys.regenerate_for_org("org_id", "key_id")

CLI

mql keys list --org ORG_ID
mql keys create -n "team-key" --org ORG_ID

Key Configuration

GET/v1/proxy-keys/:proxy_key/config

PATCH/v1/proxy-keys/:proxy_key/filters

View and update proxy key configuration, including attached content filters.

SDK & CLI Reference

Operation	TypeScript	Python	CLI
List	`mql.proxyKeys.list()`	`mql.proxy_keys.list()`	`mql keys list`
Create	`mql.proxyKeys.create(req)`	`mql.proxy_keys.create(...)`	`mql keys create`
Delete	`mql.proxyKeys.delete(id)`	`mql.proxy_keys.delete(id)`	`mql keys delete ID`
Regenerate	`mql.proxyKeys.regenerate(id)`	`mql.proxy_keys.regenerate(id)`	`mql keys regenerate ID`
Usage	`mql.proxyKeys.getUsage(id)`	`mql.proxy_keys.get_usage(id)`	`mql keys usage ID`
Test	`mql.proxyKeys.test(id, req)`	`mql.proxy_keys.test(id)`	—
List (org)	`mql.proxyKeys.listForOrg(org)`	`mql.proxy_keys.list_for_org(org)`	`mql keys list --org`