---
title: "Obtaining a credential for Boundless"
description: "How an agent gets an API key here, in the auth.md step structure. Browser-approved account setup, manual keys, and anonymous trials."
canonical: https://inference.boundless.network/auth.md
---

# auth.md

For guided local setup, read https://inference.boundless.network/setup.md, also served at https://boundless.md.
When enabled, the wizard uses browser-approved Clerk device authorization and exchanges
the resulting identity for a normal account inference key. The wizard reports if the
required deployment configuration is missing. Login methods are selected in the browser.

Boundless is operated by Boundless Networks, Inc.. A signed-in human can also create a key
at https://inference.boundless.network/api-keys. Without a human, the only credential available is the
anonymous **agent key**, minted at `POST https://inference.boundless.network/api/agent-key`, capped at
$0.01 and expiring after 24 hours.

This document follows the [auth.md](https://workos.com/auth-md) step structure. The local
setup wizard is the complete interactive walkthrough; anonymous trials remain independent.

Two hosts appear below:

- `https://inference.boundless.network/` — the console: sign-in, keys, usage, billing, documentation.
- `https://api.inference.boundless.network` — the inference API.

## Discover

For browser-approved setup, the issuer and public client ID are published in
https://inference.boundless.network/setup.md. Fetch the issuer's `/.well-known/oauth-authorization-server`
metadata and use its advertised device and token endpoints. The console publishes RFC 9728
metadata at https://inference.boundless.network/.well-known/oauth-protected-resource, naming that issuer as its
authorization server and `profile` as the only scope; it covers the setup key exchange alone.
The console's own `/.well-known/oauth-authorization-server` returns 404, because the console
is not the issuer, and the inference gateway publishes neither document.

There is no auth.md `agent_auth` block, `identity_endpoint`, `claim_endpoint`,
`register_uri` or `revocation_uri`. ID-JAG registration is not supported.
The inference API's unauthenticated 401 has no `WWW-Authenticate` discovery challenge.
Its credential is an inference key, not the temporary Clerk OAuth token.

What IS published, and is the right thing to read instead:

| Document | Path | What it gives you |
| --- | --- | --- |
| Service summary | https://inference.boundless.network/llms.txt | What this is, when to use it, how to call it |
| Full documentation | https://inference.boundless.network/llms-full.txt | Every page as one markdown file |
| OpenAPI 3.1 | https://inference.boundless.network/openapi.json | The typed API surface |
| MCP endpoint | https://inference.boundless.network/mcp | The catalog, the rate card, cost estimates and the trial mint; no credentials |
| Trial key mint | https://inference.boundless.network/api/agent-key | GET describes the offer and its caps; POST mints the key |

The MCP server needs no key, so you can read the catalog, the rate card and the
documentation — and price a workload — before anyone issues you one. Its
`create_agent_key` tool mints the same trial key as the endpoint below.

## Pick a method

Choose the interactive wizard for an account key, the console for manual issuance, or an anonymous key for a smoke test.

| Method | Supported | Detail |
| --- | --- | --- |
| `identity_assertion` with an `id-jag` token | No | No provider trust list or endpoint that accepts an ID-JAG. |
| `service_auth` | No | No registration endpoint and no claim ceremony. |
| `anonymous` | Yes, capped | A trial agent key — $0.01, 24h, tightly rate-limited — is minted at `POST https://inference.boundless.network/api/agent-key` with no credential. Real access takes a signed-in human account. |

For real workloads, use https://inference.boundless.network/setup.md to obtain a key after browser approval,
or use an existing key from your operator's environment or secret store.

## Register

**No registration endpoint, and the mint below is not one.** There is no
`/agent/identity` or equivalent on either host: nothing here binds an identity to you,
issues you a client id, or remembers that you called. Posting a registration body anywhere
will 404 or 401. Do not attempt it.

What exists instead hands a capped key to whoever asks, with no body and no credential:

```bash
curl -X POST https://inference.boundless.network/api/agent-key
```

The response carries the key, the base URL and its caps: $0.01 of credit, expires in 24 hours, limited to 6 requests and 30,000 tokens per minute. It cannot be
topped up or extended. Minting is limited to 3 an hour per
caller — a 429 there means wait, not retry harder — and the shared pool behind it has a
budget of its own, so the tier can be spent out for everyone. For a real workload, follow https://inference.boundless.network/setup.md, or give your operator these manual instructions:

> 1. Sign up or sign in at https://inference.boundless.network/sign-in. A new account is designed to be
>    active right away. Adding a card at https://inference.boundless.network/billing grants $1 of free credits.
> 2. Create a key at https://inference.boundless.network/api-keys. Copy it when it is shown; it is not
>    shown again.
> 3. Consider giving it a budget (https://inference.boundless.network/docs/billing#key-budgets) to cap what the
>    agent can spend.
> 4. Put it in the agent's environment as `BOUNDLESS_API_KEY`.

Prefer an environment variable to a chat transcript, and never echo a key back into your
output or logs.

**Consent** on a real key is satisfied by construction: a human authenticated to the
console and deliberately minted the credential, or approved the setup OAuth application in the browser.
Credits are prepaid and shared across the team, so you are spending a real balance from
your first request. A trial key has no human behind it and no consent to satisfy, which is
precisely why its ceiling is $0.01 rather than a balance.

## Claim

The interactive setup flow returns a private `device_code`, a human-readable `user_code`,
`verification_uri`, expiry, and polling interval. Keep the device code private, display
the user code and verification link, and let the user sign in and approve or deny access.
Poll the advertised token endpoint at its requested interval; honor slowdown and expiry.

Then POST https://inference.boundless.network/api/setup/key with the OAuth access token in the Bearer header.
The endpoint verifies the setup application's client ID, resolves the user's team, and
issues a normal inference key, shown once. A second request with the same token answers
`setup_recovery_required` with the key's name: inspect or revoke it in the console before
starting another grant. There is no automatic conversion of an anonymous trial key into an account key.

Either way the key carries the `llm_api` grant from the moment it is created: it can
invoke models and list the served models, but it cannot call account, key, team, billing or gateway-management routes.
The setup OAuth identity is not accepted by the inference gateway and does not broaden an inference key's grant.

## Use the credential

**This step is real.** Send the key on every request, in either header — both are accepted
on all three wire formats.

```http
Authorization: Bearer $BOUNDLESS_API_KEY
x-api-key: $BOUNDLESS_API_KEY
```

OpenAI-compatible, base URL `https://api.inference.boundless.network/v1`:

```bash
curl https://api.inference.boundless.network/v1/chat/completions \
  -H "Authorization: Bearer $BOUNDLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-v4.1-flash", "messages": [{"role": "user", "content": "Say hello"}]}'
```

Anthropic-compatible, base URL `https://api.inference.boundless.network` — the SDKs append `/v1/messages`:

```bash
curl https://api.inference.boundless.network/v1/messages \
  -H "x-api-key: $BOUNDLESS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-v4.1-flash", "max_tokens": 1024, "messages": [{"role": "user", "content": "Say hello"}]}'
```

Model identifiers come from https://inference.boundless.network/docs/pricing or the MCP `list_models`
tool. Once setup completes, use the inference key directly: it has no refresh token. A console-issued key does not expire on a schedule; a trial key
stops working 24 hours after it was minted, and then answers 401 like any
other invalid key. The team's throughput cap is charged on the tokens a request actually
used, minus any prompt tokens the gateway served from its prefix cache, so reusing a stable
prompt prefix is what buys room inside the limit.

## Errors

Inference errors are plain HTTP with a JSON body. During device authorization, handle
`authorization_pending`, `slow_down`, `access_denied`, and `expired_token` as described
in the wizard. Setup exchange can return 401 for invalid tokens, 403 for a wrong client or
restricted account, 409 for pending/recovery/key issuance states, 429 for throttling, and
503 for unavailable setup. Never restart authorization automatically after a failed mint.

| Status | What happened | What to do |
| --- | --- | --- |
| 401 | Key missing, malformed, revoked, or a trial key past its 24 hours | Do not retry unchanged. Try the other header form once; if it still fails, the key is invalid and a human must issue a new one. |
| 429 — throughput | Over the team's tokens-per-minute cap | Not charged. Back off exponentially and lower concurrency; the window is 60 seconds and rolls continuously. |
| 429 — credits | Team credits exhausted | Retrying will not help. The operator tops up at https://inference.boundless.network/billing. |
| 429 — key budget | The key spent its own budget; the team still has credits | Retrying will not help. Raise the key's budget or use a key without one. |
| 4xx other | Malformed request or unknown model | Fix the payload. Do not retry unchanged. |
| 5xx | Transient fault | Exponential backoff, retry the same request. |

Three conditions share status 429 and only one is worth retrying hard. Read the error
before choosing a strategy: a retry loop against an exhausted balance never succeeds.

## Revocation

**No inference-key revocation endpoint for agents.** Manage these keys in the console.
Discard temporary OAuth credentials after setup; their lifetime is separate from the inference key.

Revocation has one layer and a human drives it: a member deletes the key at
https://inference.boundless.network/api-keys, or a team admin removes the member, which stops their keys.
It takes effect for subsequent requests. A trial key has no console entry and nobody to
delete it — it lapses on its own 24-hour clock.

What you observe is a 401 on every request, with no warning and nothing that distinguishes
a revoked key from a mistyped one. For a revoked account key, stop and report the 401 to your operator.
They can create another key in the console or approve a fresh setup flow. **If you leak a key, say so immediately** so it can be deleted; never send a key to
support by email.

## Contact

Support is a human at <support@boundless.network>. Include the account email, the model identifier
and a request timestamp, and what you expected against what happened. **Never send an API
key.** For access, email the same address and describe the workload.