CAS HTTP API

openweights-cas listens on 8080 inside its container. The complete route map lives in cas/crates/openweights-cas/src/router.rs; every handler is under cas/crates/openweights-cas-core/src/handlers/.

Authentication

Three credentials reach the CAS, and one extractor resolves all of them.

API keys

Authorization: Bearer <key>

The key is 32 random bytes as base64url without padding. The CAS hashes the presented value with SHA-256 and compares it against api_keys.key_hash, stored as raw bytes. Plaintext is never stored and never logged.

Successful lookups are cached in process for 5 seconds, which bounds how long a revoked key keeps working.

Xet tokens

A bearer value shaped like a JWT (three dot-separated segments beginning ey) is routed to the Xet token path instead of the API-key path. The same token is also accepted in a dedicated header:

X-Xet-Access-Token: <jwt>

These are HS256 tokens the CAS itself minted from XET_JWT_SIGNING_KEY through xet-write-token and xet-read-token. hf_xet presents them during a transfer.

Session cookie

openweights_session=<uuid>; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=604800

Minted by the sign-in routes, consumed by /admin/*. Valid for 7 days, with the expiry refreshed on each authenticated request.

Scopes

The wire format uses the console's names; the database enum uses its own.

Scopes are stored as an array, so a readwrite key holds both upload and download. An unknown or revoked key returns 401; a valid key without the required scope returns 403. 401 always wins.

Status codes

Every handler error maps through one taxonomy.

Hash mismatches return both hashes in the body. Shard-version rejections echo the supported header and footer versions.

Rate limits

Redis-backed token buckets, keyed per API key, applied to the transfer routes.

The admin class is defined at 600 per minute. The /admin/* routes are gated by the session cookie rather than by a bucket.

Health and metrics

Xet CAS protocol

Shard upload responds {"result": <0|1>}, where 0 is Exists and 1 is SyncPerformed.

Hugging Face Hub API

The subset hf upload and hf download actually call.

Both token endpoints require XET_JWT_SIGNING_KEY to be set. While it is empty they return 500.

PUT /lfs/objects/{oid} takes no credential by design. It is content-addressed: the body is hashed and must match the oid in the path, so it can only write the object it names, and the client reaches it only after the authenticated LFS batch handshake. A mismatch returns 400 oid_mismatch, and an oversized body returns 400 lfs_object_too_large.

Preupload classification

A file is classified regular only when it is both smaller than 10 KiB and text-like: named README.md, .gitattributes, config.json, or tokenizer.json, or ending in .md, .txt, or .json. Everything else is lfs, which is what routes it onto the Xet transfer.

Resolve

resolve answers 302 with Location pointing at /lfs/objects/{oid} or /xet/files/{hash}, both prefixed with CAS_PUBLIC_URL and carrying ?r=<repo id> for the download counter. It also sets x-linked-size and x-linked-etag.

When OPENWEIGHTS_GATEWAY_READS is true and the file is a Xet file, resolve additionally sets X-Xet-Hash and X-Xet-Refresh-Route, which is what makes hf_xet take the reconstruction path rather than following the redirect.

Repository names

Between 1 and 96 characters, ASCII letters, digits, -, _, and ., and not starting with .. Anything else returns 400 invalid_repo_name.

Repositories are owned by the account behind the key. The organization field and the <owner> you type are display labels.

Public catalog

Readable without a credential. Private repositories are excluded; a bearer token identifies you as a viewer so your own private repositories resolve.

Sign-in

Password comparison is constant-time over SHA-256 digests. The password admin is a single synthetic user at id -1, which cannot collide with a GitHub numeric id.

Admin

Session-cookie authenticated. A missing, expired, unknown, or revoked session returns 401.

Key names are trimmed, must be non-empty, and are capped at 80 characters.

These routes are gated on a valid session, and any signed-in account reaches them. /admin/me, /admin/keys, and /admin/stats scope their results to the calling account, so you see your own identity, keys, and usage. /admin/xorbs, /admin/stats/map, and /admin/setup/status report on the deployment as a whole. Run with password sign-in and that is a single operator; run with GitHub OAuth and it is everyone who can sign in.

CORS

The CAS allows exactly one cross-origin origin, the value of CONSOLE_BASE_URL, with credentials enabled. It allows GET, POST, DELETE, PUT, and OPTIONS, and the Authorization, Content-Type, Accept, and Origin headers. A console served from any other origin cannot make credentialed calls.

Routes deliberately absent

HEAD /v1/xorbs/..., HEAD /v1/files/..., /simulation/*, /v1/fetch_term, and /v1/get_xorb/... are not implemented: they are not in the Xet OpenAPI spec and the production client never calls them. There are no DELETE routes on the Xet surface, because Xet CAS storage is append-only.