Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.baseten.co/llms.txt

Use this file to discover all available pages before exploring further.

In Frontier Gateway, every API key belongs to a federated user: the resource that owns one downstream customer’s customer_id, model set, and rate and usage limits. You manage users with POST/GET/DELETE /v1/gateway/users[...] and mint, list, or revoke their keys with POST/GET/DELETE /v1/gateway/users/{user_id}/api_keys[...]. This page walks the full lifecycle: creating a user, minting a key, listing and revoking keys, and soft-deleting the user when their account closes.

​
Concepts

A federated user maps a single downstream customer of yours into Frontier Gateway. The user owns:
  • A customer_id: a stable identifier you choose, unique within your workspace. Use it to map the user back to your own system. The customer_id is included as externalCustomerId on every billing webhook event for the user’s keys.
  • A model set: the slugs the user is allowed to call.
  • Rate and usage limits: per-model TOKEN/REQUEST ceilings enforced on every call. Limits live on the user, not on the key.
A federated API key is a credential bound to one federated user. Keys are minted under the user; rotating credentials for a customer means revoking and reissuing the key without touching the user. Each key has a prefix (the substring before the . in the full key string) used as the path parameter in every per-key URL. The plaintext secret after the . is shown once at creation and is never retrievable; lose it and you must revoke and reissue. The model set on the user is the maximum scope a key can be authorized for. When you mint a key, you can optionally restrict it to a subset of the user’s slugs; the key can never call slugs that aren’t on the user.

​
Create or update a user

Upsert a federated user with POST /v1/gateway/users. The body specifies the user’s customer_id and the complete list of models with their rate and usage limits. The endpoint is upsert by customer_id: a request with a customer_id that already exists in your workspace updates that user instead of creating a new one. The models list defines the user’s complete model set with set semantics. Slugs added to the list are added to the user, and slugs currently on the user but absent from this list are removed (cascading to existing keys’ access). 
curl --request POST \
  --url https://api.baseten.co/v1/gateway/users \
  --header "Authorization: Api-Key $BASETEN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "customer_id": "cust_42",
    "models": [
      {
        "slug": "your-org/your-model",
        "rate_limits": [
          { "type": "TOKEN", "unit": "MINUTE", "threshold": 1000000 },
          { "type": "REQUEST", "unit": "MINUTE", "threshold": 100 }
        ],
        "usage_limits": [
          { "type": "TOKEN", "unit": "DAY", "threshold": 10000000 }
        ]
      }
    ]
  }'
The response is the upserted user. Save the id. It’s the path parameter for every per-user operation that follows. 
{
  "id": "abc123hash",
  "customer_id": "cust_42",
  "models": [
    {
      "slug": "your-org/your-model",
      "rate_limits": [
        { "type": "TOKEN", "unit": "MINUTE", "threshold": 1000000 },
        { "type": "REQUEST", "unit": "MINUTE", "threshold": 100 }
      ],
      "usage_limits": [
        { "type": "TOKEN", "unit": "DAY", "threshold": 10000000 }
      ]
    }
  ],
  "created_at": "2026-05-05T12:00:00Z"
}
The models list must be non-empty. To remove all models from a user, delete the user instead. For the limit-shape reference, see Rate and usage limits.

​
List users

Fetch federated users for your workspace with GET /v1/gateway/users. Results are cursor-paginated: the default page size is 100 and the maximum is 1000. Pass ?customer_id= to look up a single user by their external identifier. 
curl --request GET \
  --url https://api.baseten.co/v1/gateway/users \
  --header "Authorization: Api-Key $BASETEN_API_KEY"
The response includes a pagination block with has_more and a cursor you pass back to fetch the next page: 
{
  "items": [
    {
      "id": "abc123hash",
      "customer_id": "cust_42",
      "models": [
        {
          "slug": "your-org/your-model",
          "rate_limits": [
            { "type": "TOKEN", "unit": "MINUTE", "threshold": 1000000 }
          ],
          "usage_limits": [
            { "type": "TOKEN", "unit": "DAY", "threshold": 10000000 }
          ]
        }
      ],
      "created_at": "2026-05-05T12:00:00Z"
    }
  ],
  "pagination": {
    "has_more": true,
    "cursor": "aVd2Yk54T2d2V0dFWE13R1l4R2k5UVE="
  }
}
To fetch the next page, pass the previous response’s cursor: 
curl --request GET \
  --url "https://api.baseten.co/v1/gateway/users?cursor=aVd2Yk54T2d2V0dFWE13R1l4R2k5UVE=" \
  --header "Authorization: Api-Key $BASETEN_API_KEY"
You’ve drained the result set when the response has "has_more": false and "cursor": null.

​
Mint an API key

Mint a new API key for an existing federated user with POST /v1/gateway/users/{user_id}/api_keys. The path parameter is the user’s internal id (not their customer_id). The body has two optional fields:
  • name: a display name for the key.
  • models: a subset of the user’s model slugs the key may be used for. Omit it to default to the user’s full model set; every slug you list must already be on the user.
curl --request POST \
  --url https://api.baseten.co/v1/gateway/users/abc123hash/api_keys \
  --header "Authorization: Api-Key $BASETEN_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "prod-key-1"
  }'
The response contains the plaintext key, returned exactly once, plus the per-model config the key was provisioned with: 
{
  "api_key": "aBcDeFg.<api-key-secret>",
  "prefix": "aBcDeFg",
  "name": "prod-key-1",
  "models": [
    {
      "slug": "your-org/your-model",
      "rate_limits": [
        { "type": "TOKEN", "unit": "MINUTE", "threshold": 1000000 }
      ],
      "usage_limits": [
        { "type": "TOKEN", "unit": "DAY", "threshold": 10000000 }
      ]
    }
  ]
}
This is the only time the key is returned in plaintext. Save it now: Baseten doesn’t store the secret portion and can’t show it to you again. If you lose it, revoke the key and mint a new one.
To rotate a customer’s credentials without changing their limits, mint a new key under the same user, hand the new key to the customer, then revoke the old one once they’ve cut over.

​
List a user’s keys

Fetch the keys belonging to a federated user with GET /v1/gateway/users/{user_id}/api_keys. Results are cursor-paginated with the same shape as the user list. 
curl --request GET \
  --url https://api.baseten.co/v1/gateway/users/abc123hash/api_keys \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "items": [
    {
      "prefix": "aBcDeFg",
      "name": "prod-key-1",
      "rate_limits": {
        "your-org/your-model": [
          { "type": "TOKEN", "unit": "MINUTE", "threshold": 1000000 }
        ]
      },
      "usage_limits": {
        "your-org/your-model": [
          { "type": "TOKEN", "unit": "DAY", "threshold": 10000000 }
        ]
      },
      "external_metadata": {
        "customer_id": "cust_42"
      }
    }
  ],
  "pagination": {
    "has_more": false,
    "cursor": null
  }
}
To fetch a single key by prefix, use GET /v1/gateway/users/{user_id}/api_keys/{api_key_prefix}: 
curl --request GET \
  --url https://api.baseten.co/v1/gateway/users/abc123hash/api_keys/aBcDeFg \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

​
Revoke a key

Revoke a single key with DELETE /v1/gateway/users/{user_id}/api_keys/{api_key_prefix}. Other keys under the same user are unaffected. 
curl --request DELETE \
  --url https://api.baseten.co/v1/gateway/users/abc123hash/api_keys/aBcDeFg \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "prefix": "aBcDeFg"
}
Revocation is irreversible. After this call, the key can’t authenticate any request and can’t be restored. To restore access for the same downstream customer, mint a new key under the same federated user.

​
Delete a user

When a downstream customer churns, soft-delete their federated user with DELETE /v1/gateway/users/{user_id}. This soft-deletes the user, soft-revokes all of its keys, and frees the customer_id for reuse. You can call POST /v1/gateway/users again with the same customer_id to provision a fresh user. 
curl --request DELETE \
  --url https://api.baseten.co/v1/gateway/users/abc123hash \
  --header "Authorization: Api-Key $BASETEN_API_KEY"

{
  "id": "abc123hash",
  "customer_id": "cust_42",
  "deleted_at": "2026-05-05T12:34:56Z"
}
To revoke a single key without churning the whole user, use Revoke a key instead.

​
Next steps