Introduction

The Bodek API gives you one base URL for every service. Each service has its own per-service key, created in the developer console.

Base URL   https://dev.bodek.us/v1/<service>/…
Services   files · forms · iam · users
Format     JSON over HTTPS (file uploads use multipart/form-data)

Signing people in to your app with their Bodek account is a separate product — Bodek OAuth — that uses OAuth client credentials instead of API keys.

API catalog

Each API page is the authoritative, endpoint-by-endpoint reference. For uptime checks, GET /v1/files/health and GET /v1/forms/health answer without a key.

Getting access

1. Sign in to this site with your Bodek account (Sign in). The developer console requires an active Bodek plan; if yours isn't active you'll be sent to billing.
2. Create a key in the console for the service you want — Files, Forms and IAM keys are self-service.
3. Users API only: submit an access request first. After an administrator approves it, the Users service becomes available when creating keys.
4. For “Sign in with Bodek”, register an app in the OAuth apps console instead — see the OAuth guide.

API keys

Keys look like bf_live_ or bf_test_ followed by 32 characters (A–Z, 2–7). The full key is shown once, when you create it; only a hash is stored, and the console shows its prefix afterwards. When creating a key you choose:

Scopes, workspace and origins can't be edited later — create a new key instead. Revoke disables a key immediately (requests then fail with 401 token_revoked) but keeps it listed; Delete removes it entirely.

Authentication

Send your key as a bearer token on every request:

curl https://dev.bodek.us/v1/files/files \
  -H "Authorization: Bearer bf_live_ABCDEFGHIJKLMNOPQRSTUVWXYZ234567"

Treat keys like passwords: keep them server-side, and if one leaks, revoke it in the console and create a new one.

Sign in with Bodek

Separate from API keys, Bodek Accounts is an OAuth 2.0 provider with OpenID Connect–style discovery and UserInfo. Add a “Sign in with Bodek” button so people log into your site with their Bodek account — password and two-factor handled entirely by Bodek, no credentials touching your app.

Register a client in the OAuth apps console and follow the integration guide for the authorization-code and PKCE flows, refresh tokens, UserInfo, introspection and revocation.

Scopes & services

These are all the scopes you can pick when creating a key. A request needs the scope listed on its endpoint in the API reference; otherwise it fails with 403 insufficient_scope.

Note the separators: Forms scopes use a dot (forms.read), the others a colon.

Response format

Files, Forms and IAM wrap successful payloads in data, with optional meta for pagination:

{
  "data": [ … ],
  "meta": { "limit": 25, "offset": 0, "total": 134 }
}

The Users API returns its result object at the top level (see Users conventions). Deletes may return 204 No Content with an empty body. File downloads return the raw bytes with the file's Content-Type and a Content-Disposition header.

Errors, on every service, carry a stable machine code and a human message, plus details when there's more to say:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key needs the scope: forms.submit",
    "details": { "required": ["forms.submit"] }
  }
}

Branch on error.code, not on the message text.

Pagination

List endpoints return a page at a time and describe it in meta:

• Forms — limit and offset query parameters; meta has limit, offset and total. Request the next page with offset = offset + limit until you've read total items.
• Files — limit (1–100, default 20) and offset, with an optional sort (name_asc or name_desc). Follow meta.next_offset and stop when it is null; the Files reference lists exactly which parameters each list endpoint takes.

Errors

Request IDs

Every response from a service includes an X-Request-Id header (a 20-character hex string). It is also recorded in your key's audit log. Log it on your side and quote it in bug reports so we can find the exact request.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-Id: 8069ab8f752950692a1c
X-RateLimit-Limit-Minute: 120
X-RateLimit-Remaining-Minute: 119
X-RateLimit-Reset-Seconds: 42
X-RateLimit-Limit-Day: 20000
X-RateLimit-Remaining-Day: 19873

Rate limits

Each key has a per-minute cap and a rolling 24-hour cap, set when you create it (defaults 120/minute, 20,000/day). Every authenticated request counts, including ones that fail. Responses carry:

Over a cap you get 429 rate_limited with error.details.limit. Wait for the reset (or back off exponentially) before retrying. The console shows each key's usage over the last 24 hours.

Origin restrictions

A key with no allowed origins works from anywhere. A key with allowed origins only accepts requests whose Origin header — or, if absent, Referer — has a matching host:

• app.example.com matches that host exactly.
• *.example.com matches any subdomain and example.com itself.
• A request with neither header (a typical server-side call) is rejected with 403 origin_required; a non-matching host gets 403 origin_blocked.

So use origin-restricted keys for browser code (publishable keys) and unrestricted keys, kept secret, on your servers. Origin checks happen in the service and work the same through the gateway and the direct hosts. (Server-only and IP-allow-list modes exist for keys provisioned by Bodek; IP-restricted keys should call the direct hosts rather than the gateway.)

CORS & browsers

The gateway supports cross-origin calls from browsers. It answers OPTIONS preflights with 204 and echoes the caller's Origin in Access-Control-Allow-Origin (no cookies — Access-Control-Allow-Credentials: false; authenticate with the Authorization header).

Access-Control-Allow-Methods:  GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
Access-Control-Allow-Headers:  Authorization, Content-Type, Accept, Range, If-Range, If-None-Match,
                               If-Modified-Since, If-Match, Idempotency-Key, X-Requested-With
Access-Control-Expose-Headers: X-Request-Id, X-RateLimit-*, Content-Disposition, Content-Range,
                               Accept-Ranges, ETag, Last-Modified, Location, Retry-After
Access-Control-Max-Age:        86400

CORS only lets the browser read the response; whether the request is allowed is decided by the key's origin restrictions. Never ship an unrestricted key in browser code.

Gateway & direct hosts

Use the gateway unless you have a reason not to. It forwards the method, path, query string, body (JSON, raw, or multipart uploads), Authorization, and download/caching headers (Range, If-None-Match…) to the service, and relays the status code, body and response headers such as Content-Type, Content-Disposition, Content-Range, ETag, Location, X-Request-Id and X-RateLimit-*. Redirects (for example a 302 to a temporary download URL) are passed back to your client to follow.

The same key works on both. The gateway allows up to 60 seconds per request; for very large uploads or downloads, or IP-restricted keys, call the direct host. An unknown service name returns 404 unknown_service.

Migrating from file.bodeksolutions.com

Existing Files API keys keep working. Swap the base URL — https://file.bodeksolutions.com/api/v1 → https://dev.bodek.us/v1/files — and leave every resource path (/files, /folders, /shares/{id}) unchanged.