Management API

The Management API lets you run key management from your own scripts: create and revoke keys, adjust spend limits, and read spend and request logs.

Management keys

You call the Management API with a management key. Each organization gets one, issued by Consus on request (sales@consusindustries.co). Send it in the x-api-key header like any other key. A management key:

Can’t run inference. Model endpoints and GET /v1/models return 403 management_key_not_permitted.
Only sees your organization. A key ID from another organization returns 404.
Can’t touch management keys, including itself. To rotate it, contact Consus.
Expires after 180 days. After that, calls return 403 management_key_expired and the key is deleted. GET /v1/org shows the expiry date, so ask Consus to rotate it before then.
Isn’t subject to spend caps, so it keeps working after your organization hits its budget.

It can create keys, so protect it at least as carefully as your other keys.

Keys

Keys you create here are ordinary inference keys. They count toward your organization’s spend cap. An internal key follows the same model policy as keys created in the portal: its owner’s. An external key has its own (see below).

Internal and external keys

There are two types of keys: internal and external. Every key is internal unless you mark it external, including every key created before this setting existed. You choose the type when you create a key, and it can’t be changed afterward. If you need a key of the other type, create a new one. The management key and your portal administrators can create external keys; portal members create internal keys. External keys are available once Consus enables them for your organization. When they are, GET /v1/org shows external_markup: the markup your contract sets for external keys. Consus sets it; it can’t be changed through the API. Until then, external_markup is null and creating an external key returns 400 external_not_enabled. An external key doesn’t take its owner’s model policy. When you create it, set policy_id to one of your organization’s grant policies (listed under policies on GET /v1/org) and the key can use only that policy’s models. Leave policy_id out and the key can use every model your organization allows. Your portal administrators can change or clear an external key’s policy later. External keys don’t count toward their owner’s key limit.

List keys

GET /v1/keys

Parameter	Default	Description
`status`	`active`	`active`, `revoked`, or `all`
`owner`	—	Only keys owned by this email (case-insensitive)
`billing_class`	—	`internal` or `external`

{
  "object": "list",
  "period": "2026-09",
  "data": [
    {
      "key_id": "a1b2c3d4e5",
      "label": "ci-runner",
      "owner": "dev@example.com",
      "billing_class": "internal",
      "status": "active",
      "created": "2026-09-01",
      "monthly_limit_usd": 50.0,
      "expires": "2027-09-01",
      "month_to_date_cost_usd": 12.5
    }
  ]
}

status can also be unmanaged: an older key with no per-key cap. It still works. revoked covers every key that no longer works: revoked by you, expired, turned off after 35 days without requests, or deleted. monthly_limit_usd is null when the key relies on the organization cap alone. expires is the last day the key works. Every key has one, 12 months after it was created unless you asked for an earlier date.

Get a key

GET /v1/keys/{key_id} returns the list fields plus allowed_models, person_monthly_limit_usd, max_spend_usd (trials only), and lifetime_cost_usd.

Create a key

POST /v1/keys

{
  "owner": "dev@example.com",
  "label": "ci-runner",
  "billing_class": "external",
  "policy_id": "standard",
  "description": "GitHub Actions",
  "requested_monthly_limit_usd": 50,
  "expires": "2027-03-31"
}

owner is required and can’t be changed later.
label is up to 64 characters: letters, digits, spaces, and . _ @ % + -.
billing_class is internal or external and can’t be changed later. Leave it out for an internal key.
policy_id is for external keys only: a grant policy from GET /v1/org. Leave it out and the key can use every model your organization allows. Sending it on an internal key returns 400.
requested_monthly_limit_usd is capped at your organization’s limit. Leave it out to use your organization’s default.
expires is optional: a date (YYYY-MM-DD) no more than 12 months away. Leave it out and the key expires 12 months from today. The key stops working the day after this date.

Any other field returns 400. Your portal administrators set model access for internal keys. The response includes the key’s secret. It’s shown once:

{ "key_id": "f6g7h8i9j0", "value": "gr_live_…", "monthly_limit_usd": 50.0, "expires": "2027-03-31", "billing_class": "external" }

Your organization needs a monthly spend cap before you can create keys. Without one, you get 409 org_cap_required. Each person can hold a limited number of active internal keys, and each organization a limited total of keys (revoked keys count).

Revoke a key

DELETE /v1/keys/{key_id} disables the key immediately. At least 30 days later the key itself is deleted for good. It keeps appearing in GET /v1/keys?status=revoked, in spend reports, and in request logs.

Change a key’s limit

PATCH /v1/keys/{key_id}/limit with {"requested_monthly_limit_usd": 25}. The amount must be positive and is capped at your organization’s limit. Like creating keys, this needs an organization spend cap.

Rename a key

PATCH /v1/keys/{key_id}/metadata with {"label": "ci-runner-2"}. Only the label changes. A key’s owner and type are fixed: sending owner or billing_class returns 400. To change either, create a new key (and revoke the old one if you no longer need it).

Organization

GET /v1/org

{
  "org_id": "example",
  "period": "2026-09",
  "org_monthly_limit_usd": 5000.0,
  "default_monthly_limit_usd": 200.0,
  "enabled_models": ["claude-sonnet-4-5:il5", "gpt-5.4:il5"],
  "month_to_date_cost_usd": 1234.56,
  "active_keys": 12,
  "revoked_keys": 3,
  "prepaid_credit_usd": null,
  "contract_start": null,
  "external_markup": 1.35,
  "management_key_expires": "2027-03-24",
  "policies": [
    {
      "policy_id": "standard",
      "name": "Standard",
      "mode": "grant",
      "allowed_models": ["claude-sonnet-4-5:il5"]
    },
    {
      "policy_id": "no-itar",
      "name": "No ITAR",
      "mode": "restrict",
      "allowed_models": ["gpt-5.4:itar"]
    }
  ]
}

null means not set: no organization cap, the Consus default per-key cap, no model restriction, or no external markup on file. external_markup is the markup your contract sets for external keys. Consus sets it. policies lists your organization’s model policies, which your portal administrators manage. A grant policy gives the models listed (null means every model your organization allows); a restrict policy removes the models listed. Use a grant policy’s policy_id when you create an external key.

Spend

GET /v1/spend returns monthly spend per key.

Parameter	Default	Description
`start`	same as `end`	First month, `YYYY-MM`
`end`	this month	Last month, `YYYY-MM`
`api_key_id`	—	Only this key

You can request up to 3 months for the whole organization, or 12 for one key.

{
  "object": "list",
  "start": "2026-08",
  "end": "2026-09",
  "data": [
    {
      "api_key_id": "a1b2c3d4e5",
      "period": "2026-09",
      "requests": 1042,
      "input_tokens": 1830221,
      "output_tokens": 240118,
      "cached_input_tokens": 902330,
      "cost_usd": 12.5
    }
  ],
  "totals": [
    { "period": "2026-08", "requests": 0, "input_tokens": 0, "output_tokens": 0, "cached_input_tokens": 0, "cost_usd": 0.0 },
    { "period": "2026-09", "requests": 1042, "input_tokens": 1830221, "output_tokens": 240118, "cached_input_tokens": 902330, "cost_usd": 12.5 }
  ]
}

Organization reports skip months where a key had no activity. totals always covers every month.

Request logs

GET /v1/logs returns your organization’s per-request logs, newest first. Logs hold metadata only: token counts, cost, latency, and status. The gateway never stores prompts or responses (zero data retention).

Parameter	Default	Description
`start`	30 days before `end`	Window start, ISO 8601 UTC. A bare date means midnight.
`end`	now	Window end. A bare date includes the whole day. Max window: 90 days.
`status`	`all`	`all`, `success` (HTTP 200), or `errors` (everything else)
`api_key_id`	—	Only this key
`limit`	100	Rows per page, 1–1000
`cursor`	—	`next_cursor` from the previous page. Don’t build or edit it.

{
  "object": "list",
  "data": [
    {
      "request_id": "9c5b2f1a-8d3e-4b6a-9f21-0e7c44aa1b55",
      "timestamp": "2026-08-04T17:22:31.481923+00:00",
      "api_key_id": "a1b2c3d4e5",
      "model": "claude-sonnet-4-5:il5",
      "compliance": "il5",
      "reasoning_effort": "high",
      "input_tokens": 1204,
      "output_tokens": 356,
      "cost": 0.00897,
      "latency_ms": 2841,
      "status": "200"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ2IjoxLCJ3bSI6..."
}

request_id matches the X-Request-ID header the caller received. compliance is the level from the model ID, or null if the request never resolved a model. status is the HTTP status the caller got, so errors appear alongside successes.

Pagination

While has_more is true, pass next_cursor back as cursor. The cursor fixes the time window, so new traffic won’t shift your pages. Keep the other parameters the same between pages. Loop on has_more, not on the size of data. A narrow filter can return an empty page that still has more after it.

What logs leave out

Logs include model errors and malformed requests. They leave out requests refused before metering:

At the edge: bad or missing keys, WAF blocks, rate limiting.
By key policy: a key over its spend cap (402), an expired trial (403), or a management key trying inference (403).

If a key stops producing log entries, check its spend cap and expiry first.

Example

# Create a key for a new engineer
curl -X POST "https://api.consus.io/v1/keys" \
  -H "x-api-key: $CONSUS_MANAGEMENT_KEY" \
  -H "content-type: application/json" \
  -d '{"owner": "dev@example.com", "label": "dev-laptop", "requested_monthly_limit_usd": 50}'

# See everything they own
curl "https://api.consus.io/v1/keys?owner=dev@example.com" \
  -H "x-api-key: $CONSUS_MANAGEMENT_KEY"

# Revoke a key when they leave
curl -X DELETE "https://api.consus.io/v1/keys/a1b2c3d4e5" \
  -H "x-api-key: $CONSUS_MANAGEMENT_KEY"

import requests

BASE = "https://api.consus.io"
H = {"x-api-key": MANAGEMENT_KEY}

def offboard(owner):
    keys = requests.get(f"{BASE}/v1/keys", headers=H, params={"owner": owner}, timeout=30)
    keys.raise_for_status()
    for key in keys.json()["data"]:
        requests.delete(f"{BASE}/v1/keys/{key['key_id']}", headers=H, timeout=30).raise_for_status()

def logs(**params):
    cursor = None
    while True:
        page = requests.get(
            f"{BASE}/v1/logs", headers=H, params={**params, "cursor": cursor}, timeout=30
        ).json()
        yield from page["data"]
        if not page["has_more"]:
            return
        cursor = page["next_cursor"]

Errors

Status	Type	Meaning
`400`	`invalid_request_error`	Bad parameter, bad body, unknown field, or bad cursor
`400`	`external_not_enabled`	External keys aren’t enabled for your organization yet
`400`	`invalid_external_policy`	`policy_id` isn’t one of your organization’s grant policies
`401`	`authentication_error`	No API key
`403`	`permission_error`	Not a management key
`403`	`management_key_not_permitted`	Management key used outside the Management API
`403`	`management_key_expired`	Management key is past its 180 days
`404`	`not_found`	Not one of your organization’s keys
`409`	`org_cap_required`	Your organization needs a monthly spend cap first
`409`	`max_keys_reached`	This owner has the maximum number of active internal keys
`409`	`org_key_limit_reached`	Your organization has reached its key limit
`502`	`admin_upstream_error`	Creating or revoking the key failed upstream. No usable key was left behind. Retry.
`503`	`admin_unavailable` / `server_error`	Temporarily unavailable. Retry shortly.

Product

Getting Started

API Reference

Integrations

Management keys

Keys

Internal and external keys

List keys

Get a key

Create a key

Revoke a key

Change a key’s limit

Rename a key

Organization

Spend

Request logs

What logs leave out

Example

Errors

​Management keys

​Keys

​Internal and external keys

​List keys

​Get a key

​Create a key

​Revoke a key

​Change a key’s limit

​Rename a key

​Organization

​Spend

​Request logs

​Pagination

​What logs leave out

​Example

​Errors

Management keys

Keys

Internal and external keys

List keys

Get a key

Create a key

Revoke a key

Change a key’s limit

Rename a key

Organization

Spend

Request logs

Pagination

What logs leave out

Example

Errors