Authentication

Every authenticated request to the CloudRaker API carries a single header:

Authorization: Bearer <token>

The gateway accepts two kinds of token under that header and tells them apart automatically:

1. organization API keys — the developer story. A machine credential scoped to one organization.
2. Session JWTs — what the web app uses for a signed-in human. They carry that person’s role and per-resource grants.

Both resolve to the same tenant-scoped identity, so they can call the same routes — with one exception covered under Capability differences below.

Organization API keys

An org API key is a long-lived credential that belongs to your organization, not to a person. Its actions are recorded under the key’s name. Use it for server-to-server automation.

Create a key

Keys are created in the app under Admin → API keys (admin-only). The API keys guide has the full UI walkthrough. The plaintext value is shown once at creation and is never retrievable again.

You can also manage keys over the API (admin-gated):

1
curl https://api.cloudraker.com/api-keys \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json"

1
curl -X POST https://api.cloudraker.com/api-keys \
2
     -H "Authorization: Bearer <token>" \
3
     -H "Content-Type: application/json" \
4
     -d '{
5
  "name": "Primary Integration Key",
6
  "permissions": [
7
    "read:users",
8
    "write:projects",
9
    "delete:logs"
10
  ],
11
  "canImpersonate": true
12
}'

1
curl -X DELETE https://api.cloudraker.com/api-keys/id \
2
     -H "Authorization: Bearer <token>"

Use a key

Send it as the bearer token on any request:

1
curl https://api.cloudraker.com/me \
2
     -H "Authorization: Bearer <token>"

Tenant scoping

One organization is one tenant. After it authenticates you, the gateway derives your tenant from the token’s org and scopes every call to it — you never send a tenant id, org id, or slug yourself. A token whose identity has no organization gets 404 {"error":"org not found"}.

API keys vs. session JWTs

Both token kinds resolve to the same tenant, but they differ on one class of route:

An org key is treated as an org-level machine credential: it passes admin and API-key gates, but it has no user membership, so routes gated on a specific human’s fine-grained resource permission can’t be satisfied by a key. Org admins bypass per-resource space checks regardless.

Session JWTs

Session JWTs are three-segment JWTs minted for a signed-in user by the web app’s auth flow. They’re verified against the platform’s signing keys and carry the user’s role, permission claims, and membership id. You don’t mint these yourself for server-to-server work — reach for an API key instead. They’re documented here so you recognize them when the web app or an SDK forwards one.

Failure codes

Where to go next