Docs/Authentication
◆ Authentication

Auth for every use case.

API keys for server-to-server scripts. OAuth 2.0 for third-party apps that act on behalf of a dealership. SAML and OIDC single sign-on for Fleet-plan customers who run their own identity provider. All tokens are scoped, rotatable, and short-lived.

  • API keys · per-environment · per-scope · rotatable
  • OAuth 2.0 · authorization_code + client_credentials · PKCE
  • SSO · SAML 2.0 + OIDC · JIT provisioning · group-role mapping
  • All credentials logged and auditable for 13 months
Generate an API key OAuth app setup
Three modes

Pick the right one.

Server-to-server integrations want API keys. Third-party apps acting on behalf of dealerships want OAuth. Large dealer groups with their own IdP want SSO.

API keys

For backend scripts, internal tooling, and anything server-to-server.

  • — sk_live_... / sk_test_...
  • — Scoped at creation, immutable after
  • — Rotatable with zero downtime
  • — Per-key rate limits

OAuth 2.0

For third-party apps listed in our partner directory.

  • — authorization_code + client_credentials
  • — PKCE required for public clients
  • — Refresh tokens · sliding 30-day TTL
  • — Per-dealership install flow
https://auth.boater.os/authorize?
client_id=...&scope=hulls:read

SSO Fleet

For dealer groups with their own identity provider.

  • — SAML 2.0 · Okta, Entra, Google, OneLogin
  • — OIDC · any compliant IdP
  • — Just-in-time user provisioning
  • — IdP group → BoaterOS role mapping
Scopes

Eight scopes. Grant the minimum.

Scopes are granted at key creation or OAuth consent. They cannot be widened after the fact — rotate the key or re-consent. Read and write are independent: grant one without the other.

hulls:read Read inventory, specs, photos, pricing, syndication state.
hulls:write Create, update, and archive hulls. Adjust pricing. Upload photos.
leads:read Read leads, consent records, assignment history, intent signals.
leads:write Create leads, log consent, assign owner, send SMS and email.
deals:read Read deals, offers, F&I structures, funding states.
deals:write Create and advance deals. Issue documents. Record payments.
admin Dealer settings, user provisioning, role assignment, audit log access.
webhooks Register, rotate secrets, replay events, drain DLQs.
Lifetimes + rotation

Short-lived everything.

API keys are long-lived but rotatable. OAuth access tokens expire in 60 minutes. Refresh tokens last 30 days with a sliding window. SSO sessions follow your IdP's policy.

API key
No expiry

Rotate manually. Dual-key rotation supported for 7 days.

OAuth access
60 min

Short enough to limit blast radius if leaked.

OAuth refresh
30 days

Sliding window — used tokens get a fresh 30-day clock.

SSO session
Per IdP

Honors your session policy. Force logout via SLO.

Making a request

Authorization: Bearer.

Same shape for every auth mode — API keys, OAuth access tokens, SSO session tokens. The scheme is always Bearer.

terminal · authenticated request 
# With an API key
curl https://api.boater.os/v1/hulls \
  -H "Authorization: Bearer sk_live_abc123..."

# With an OAuth access token
curl https://api.boater.os/v1/hulls \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
Security recommendations

The boring list that matters.

  • Never ship keys in client bundles. Browser, mobile, or embedded devices call your backend, which calls us.
  • Scope every key narrowly. A syndication worker needs hulls:read, nothing more.
  • Rotate on a schedule. Quarterly at minimum. Immediately on suspected leak.
  • Monitor the audit log. Every auth event is logged — use the /v1/audit endpoint or ship to your SIEM.
  • Use separate keys per environment. Test keys start with sk_test_ and cannot touch live data.
  • Enforce MFA for admin scope. Admin keys require MFA at issue time. Don't bypass it.