authentication

all api endpoints require a bearer token. tokens are scoped to your organization — all usage, rate limits, and credits are tracked per-org.

get your api key

go to the crawlbrulee dashboard and log in with your account.

navigate to api tokens

open the api tokens section from the sidebar.

create a token

click create token and give it a descriptive name (e.g. production-backend, dev-local).

copy the token

copy the token immediately. you won’t see it again — if you lose it, revoke it and create a new one.

tokens look like cwbl_ followed by a 43-character string, e.g. cwbl_Xy9fK2.... tokens issued before the prefix change carry the older cble_ prefix and keep working — no need to reissue them.

using your token

include the token in every request via the Authorization header:


Authorization: Bearer YOUR_API_KEY

curl


curl -X POST https://api.crawlbrulee.com/api/scrape \
  -H "Authorization: Bearer $CRAWLBRULEE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "extract": { "markdown": true }
  }'

js/ts


const response = await fetch('https://api.crawlbrulee.com/api/scrape', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.CRAWLBRULEE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://example.com',
    extract: { markdown: true },
  }),
})
 
const data = await response.json()
console.log(data)

js/ts sdk


import { Crawlbrulee } from '@crawlbrulee/sdk'
 
// reads CRAWLBRULEE_API_KEY from the environment
const crawlbrulee = Crawlbrulee.fromEnv()
 
const page = await crawlbrulee.scrape({
  url: 'https://example.com',
  extract: { markdown: true },
})
 
console.log(page.markdown)

python


import os
import requests
 
response = requests.post(
    "https://api.crawlbrulee.com/api/scrape",
    headers={
        "Authorization": f"Bearer {os.environ['CRAWLBRULEE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://example.com",
        "extract": {"markdown": True},
    },
)
 
data = response.json()
print(data)

python sdk


from crawlbrulee import Crawlbrulee, ScrapeExtract
 
# reads CRAWLBRULEE_API_KEY from the environment
client = Crawlbrulee.from_env()
 
page = client.scrape(
    url="https://example.com",
    extract=ScrapeExtract(markdown=True),
)
 
print(page.markdown)

environment variables

store your token in an environment variable called CRAWLBRULEE_API_KEY. this keeps it out of your source code and makes it easy to rotate.

add it to your .env file:


# .env
CRAWLBRULEE_API_KEY=cwbl_abc123...

then load it however your framework expects — dotenv, process.env, os.environ, etc.

never commit api tokens to version control. add .env to your .gitignore and use secrets management in ci/cd.

token scoping

tokens belong to an organization, not individual users. every team member’s token shares the same org-level credit balance, rate limits, and concurrency pool. there is no per-token usage isolation — if one token burns through credits, the entire org is affected. see organizations for roles, membership, and org management.

verifying a token

GET /api/whoami confirms a token is valid and returns the organization and token it belongs to — handy for checking setup or debugging auth. it never returns the full token.


curl https://api.crawlbrulee.com/api/whoami \
  -H "Authorization: Bearer $CRAWLBRULEE_API_KEY"

response:


{
  "organization_name": "Acme Inc",
  "token_name": "production",
  "token_preview": "cwbl_…a1b2"
}

field	type	description
`organization_name`	`string`	display name of the organization that owns the token
`token_name`	`string`	the name you gave the token
`token_preview`	`string`	truncated token preview (e.g. `cwbl_…a1b2`); safe to log

a 401 means the token is missing, malformed, expired, or revoked. the crawlbrulee sdk exposes this as client.whoami().

error responses

when authentication fails, the api returns a 401 status code:


{
  "name": "invalid_credentials",
  "message": "Invalid API token"
}

message is one of: Missing Authorization header, Invalid API token, API token expired, Authentication failed.

common causes:

invalid or revoked token — double-check you copied the full token, with no extra whitespace or line breaks, and that it hasn’t been revoked from the dashboard.
expired token — create a new token from the dashboard.
no Authorization header sent — the header is required; a bare token (no Bearer prefix) is accepted, but we recommend using Bearer for consistency with other tooling.

see errors for the full error reference.

security best practices

never expose api tokens in client-side code, browser requests, or public repositories. always make api calls from your server and load tokens from environment variables or a secrets manager.

rotate tokens periodically — especially after team members leave.
use separate tokens for production and development so you can revoke one without affecting the other.
monitor usage in the dashboard to catch unexpected spikes early.
you can set an optional expiration when creating a token; by default it never expires. requesting organization deletion immediately expires every token of the org, regardless of any expiration you set.
organizations are limited to 50 active tokens at a time.