offloaddocs
Type
Reference
For
Driver
Coordinator
Admin
Developer
On
Mobile app
Tablet
Desktop
API

Authentication

The Offload Public API authenticates every request with a Bearer token. One token, one organization, one header. No OAuth flow, no JWT refresh dance, just a long unguessable string in Authorization.

The same token works on every API on this portal (Imports today, and additional APIs as they ship).

Authorization: Bearer osk_live_8c2c1a7b9d5e4a2f3c1b8a5d6e7f9012_a3b4

Issuing a token

Mint a token from Settings → API Keys inside the Offload app. The flow:

  1. Log in to Offload as an organization admin.
  2. Open Settings → API Keys.
  3. Click Mint new key, give it a name (e.g., ACME twice-daily push), and copy the plaintext token from the dialog that appears. The full string is only shown once.
  4. Paste the token into your integration's secret manager.

The list view shows the prefix, the name, the last-used timestamp, and the last-used IP, enough to audit usage without exposing the full token.

A few constraints worth knowing up front:

  • One token, one organization. Every token is bound to the organization it was minted in; cross-org access is not possible.
  • Plaintext is shown once. Offload never re-displays the full token. To rotate, mint a new key and revoke the old one from the same screen (see Rotation below).
  • Revocation is immediate. Revoked tokens stop authenticating within seconds.
  • Admin access required. You need admin-level access on the organization to mint or revoke keys.

If the API Keys tab isn't visible under Settings, your organization doesn't have the public API enabled yet. Contact your Offload account team to turn it on. As a fallback while that's being arranged, Customer Success (support@letsoffload.com) can also mint a token for your organization.

Token format

osk_live_<32 base62 chars>_<4 char checksum>
  • osk_ ("Offload secret key" prefix). The recognizable prefix is what makes GitHub Secret Scanning and other automated leak detectors spot the token if it ends up where it shouldn't.
  • live (environment marker). Tokens for production data carry the live segment.
  • 32 base62 characters (the entropy). ~190 bits (32 × log₂(62)), well above the practical brute-force ceiling.
  • 4-character checksum lets the server reject malformed tokens before doing a database lookup. Catches typos and copy-paste errors with no auth-latency cost.

The full token is shown to you exactly once at creation. Offload stores only an HMAC-SHA-256 hash of the token with a server-side pepper, so even with full database access, the plaintext is unrecoverable. If you lose the token, mint a new one.

To confirm a token is live, run the one-line whoami check in the Quickstart.

Environment variable convention

Standardize on OFFLOAD_API_TOKEN across every environment your integration runs in:

# In your secret manager, your CI's secret store, or your local shell:
export OFFLOAD_API_TOKEN=osk_live_8c2c1a7b9d5e4a2f3c1b8a5d6e7f9012_a3b4
export OFFLOAD_API_BASE=https://api.letsoffload.com

Read it from process.env / os.environ and pass it as Authorization: Bearer ${OFFLOAD_API_TOKEN} on every request.

Rotation

Rotation is a manual three-step process. There's no automatic rollover, but the token list shows last-used so you can confirm the new token is live before revoking the old one.

  1. Mint the new token in Settings → API Keys. Copy it.
  2. Swap it in your environment. Update your secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, GitHub Actions secrets, wherever the token lives) and roll your integration so the new token is in OFFLOAD_API_TOKEN. Send at least one request to confirm last_used_at updates on the new token in the API Keys list.
  3. Revoke the old token. Click Revoke on the old token in the list. Revoked tokens return 401 UNAUTHORIZED on subsequent requests within a few seconds.

We recommend rotating on a fixed schedule (every 90 days is common) and after any suspected exposure.

Suspected leak

If you suspect a token has been exposed (a teammate accidentally committed it, an external system was breached, the token appeared in a log shipper you don't control):

  1. Revoke it immediately from Settings → API Keys. Revocation takes effect within seconds.
  2. Mint a replacement if the integration still needs to run, and swap it into your secret manager.
  3. If the leak was to a public GitHub repository, GitHub's Secret Scanning Partner Program will fire a webhook to Offload automatically and we'll revoke the token within ~60 seconds of the leak landing. You'll receive an email at the org admin's address with the revocation reason and the offending repository URL.

If you don't have admin access to mint/revoke in your organization, email support@letsoffload.com with the token's prefix (the osk_live_<8 chars> portion is enough, and never send the full token).

What the token can do

A token has full access to its organization's data on the public API; there are no per-resource scopes.

Token-org binding is enforced on every endpoint. A token issued for organization A cannot read or write data in organization B; cross-org requests return 404 NOT_FOUND (Offload does not leak existence by returning 403).

Errors

Every authentication failure returns 401 with the UNAUTHORIZED code in the RFC 7807 envelope:

{
  "type": "https://docs.letsoffload.com/api/errors/UNAUTHORIZED",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The Bearer token is missing, malformed, unknown, expired, or revoked.",
  "instance": "/v1/imports/jobs",
  "code": "UNAUTHORIZED",
  "requestId": "req_01HXYZ...",
  "docUrl": "https://docs.letsoffload.com/api/errors/UNAUTHORIZED"
}

The response shape is byte-identical for missing, malformed, unknown, revoked, and expired tokens. That's deliberate: a different shape per failure mode would be a timing channel an attacker could use to enumerate valid token prefixes. If your integration starts returning 401, check (in this order):

  1. Is OFFLOAD_API_TOKEN set in the environment your code is running in?
  2. Open Settings → API Keys. If the prefix you're using shows status revoked, mint a new one.
  3. Is the Authorization header formatted exactly as Bearer <token> with one space?
  4. Run the Quickstart whoami check. If it returns 401, the token has been revoked or rotated out. Confirm in the API Keys list and mint a replacement.

Next

  • Quickstart: confirm your token is live in one curl.
  • API Reference: interactive Scalar reference covering every endpoint and field.
Was this helpful?