Authentication

Every call to the CHeKT API authenticates with a Bearer token. CHeKT supports three token sources in a progression from simple to strict — start where you are, move forward as your needs grow.

The three auth modes

Each mode is independent — you can mix them across apps in the same dealer. Most partners start with an API key and stay there forever. OAuth and Assertion Tokens come into play when you've outgrown the simpler model.

The Authorization header

Whatever the mode, the wire format is the same. Send a standard Authorization header with a Bearer-prefixed token. The token value is what differs by mode:

API key

Authorization: Bearer chekt_live_8h2j3kfm… — long-lived, per-app, dealer-scoped.

OAuth access token

Authorization: Bearer eyJhbGciOiJSUzI1NiIs… — short-lived (1h), refreshable, per-user.

Assertion-derived token

Authorization: Bearer eyJhbGciOiJFUzI1Ni… — short-lived (1h), obtained by exchanging a signed JWT.

GET /v1/devices HTTP/1.1
Host: api.chekt.com
Authorization: Bearer chekt_live_8h2j3kfm2918sndlj…
Accept: application/json

API keys

API keys are the default. Every CHeKT App you create in the dealer portal gets exactly one active key. Keys are per-app, dealer-scoped, and rotatable.

Format

chekt_live_… (32+ characters). Prefix indicates environment: chekt_live_ for production, chekt_test_ for sandbox.

Scope

Limited to the app's granted permissions. The same key cannot exceed the scope set at app creation.

Lifetime

Indefinite. Keys do not expire. Rotate them yourself on the schedule that suits your risk model — quarterly is a good default.

Storage

Secret manager only. Never in code, environment files committed to git, or chat tools.

Storing the API key

Where to put your key, by platform. All five approaches are first-class; pick what matches your deployment.

# Export from a sourced ~/.zshrc or ~/.bashrc
export CHEKT_API_KEY='chekt_live_…'

# Or load from .env via direnv
echo 'export CHEKT_API_KEY="chekt_live_…"' > .envrc
direnv allow

Rotation flow

Rotation is a one-click action in the dealer portal that issues a new key and keeps the old one valid for 24 hours so you can deploy without downtime.

OAuth 2.0 (preview)

For apps that act on behalf of end users — letting a dealer admin or operator sign in and approve scopes themselves — OAuth 2.0 is the right model. We're rolling this out in Q3 2026 for select partners.

Authorization code flow

The standard three-legged OAuth flow with PKCE. The end user signs in, grants scopes, and your app exchanges the code for tokens.

authorization_endpoint

https://auth.chekt.com/oauth/authorize — where you redirect the user.

token_endpoint

https://api.chekt.com/oauth/token — where you POST to exchange the code.

access_token TTL

One hour. Use the refresh token to get a new one without re-prompting the user.

refresh_token TTL

Thirty days, sliding window. Make any API call and the window resets.

Assertion Tokens (preview)

The strictest mode. Your service signs short-lived JWTs with a private key, exchanges them at CHeKT's token endpoint for access tokens, and rotates the signing key on its own schedule. No long-lived secret ever lives on disk.

Reserve Assertion Tokens for high-volume partners running in regulated environments — central stations with SOC 2 obligations, panel manufacturers shipping to regulated markets, large-scale automation platforms.

import { SignJWT, importJWK } from 'jose';

const privateJwk = JSON.parse(process.env.PARTNER_PRIVATE_JWK!);
const key = await importJWK(privateJwk, 'ES256');

const jwt = await new SignJWT({})
  .setProtectedHeader({ alg: 'ES256', kid: 'partner-key-1' })
  .setIssuer('your-partner-id')
  .setSubject('your-partner-id')
  .setAudience('https://api.chekt.com')
  .setIssuedAt()
  .setExpirationTime('5m')
  .sign(key);

// Exchange for an access token
const res = await fetch('https://api.chekt.com/oauth/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
    assertion: jwt,
  }),
});

const { access_token } = await res.json();

IP allow lists

Layered on top of any auth mode, an IP allow list restricts API calls to known source IPs — your VPC NAT egress, your office, your CI runners. Requests from outside the list are rejected at the edge before reaching the API.

Common auth errors

The six errors that account for ~95% of auth-related calls to support.

For the full error catalogue including non-auth codes, see the error reference. Every error response includes a request_id — log it.

Best practices

Next steps