Charter Boats
Charter Boats API

Authentication

How API keys work across the Charter Boats developer surfaces

Authentication depends on which surface you're calling:

SurfaceBaseAuth
Discovery API/api/ai/*None — public, rate-limited per IP
MCP server/mcpNone — public
Agent API/api/agent/*Logged-in agent session — not a keyed surface
Operator API — reads/api/* (GET)None server-side; key only for cross-origin browser calls
Operator API — writesPOST /import/boat, DELETE /boats/:idAPI key required

The Discovery API and MCP server need no credentials at all. On the Operator API, only the two write actions actually require your key — read endpoints are open to server-side callers.

When do you actually need the key?

The Operator API guards reads with an origin check, not a hard key requirement. A request is allowed through when it comes from charter.boats (the website's own frontend) or when it has no browser Origin header at all (curl, a backend service, Google Calendar fetching an iCal feed). A cb_live_ key is enforced in two cases:

CallKey needed?
Read endpoints from your server (curl / backend)No
Read endpoints from a browser on another website (cross-origin)Yes — anti-hotlink guard
Import a boat (POST /import/boat)Yes — checked in the handler
Delete a boat (DELETE /boats/:id)Yes (or a logged-in session)
# Reads work without a key from a server
curl https://charter.boats/api/boats
 
# Writes require the key
curl -X POST https://charter.boats/api/import/boat \
  -H "X-API-Key: cb_live_abc123..." \
  -d '{ ... }'

Sending the key on every request is harmless and recommended for clarity — it's simply ignored on the read endpoints that don't require it.

What you can't do with a key

ActionWhy
Edit an existing listing's details, prices, fees, availabilityDashboard only — tied to a logged-in session
Book and pay for a charterWebsite checkout only — session + Stripe Elements

The key gives you read access plus boat import/delete. Transactional and listing-edit actions are tied to a logged-in session on charter.boats and are not exposed as keyed endpoints.

Getting an API Key

Any registered user can generate an API key from the dashboard:

  1. Log in to charter.boats
  2. Go to Dashboard → Settings → API
  3. Click Generate API Key
  4. Copy and save your key (it is only shown once)

Your API key will look like: cb_live_ followed by 32 characters.

Regenerating Your Key

If your key is compromised, you can regenerate it from the same settings page. This will immediately invalidate your old key.

Security Best Practices

Never expose your API key in client-side code, public repositories, or anywhere it could be accessed by unauthorized parties.

Recommendations

DoDon't
Store API keys in environment variablesCommit API keys to version control
Use server-side code to make API callsInclude keys in client-side JavaScript
Rotate keys periodicallyShare keys across different applications
Use different keys for dev and production

Error Responses

401 Unauthorized

Returned when an external request is missing a key:

{
  "statusCode": 401,
  "message": "API key required for external requests. Include X-API-Key header."
}

Returned when the key is malformed or unrecognized:

{
  "statusCode": 401,
  "message": "Invalid API key"
}

Previous

Quick Start

Next

API Reference

On this page