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 — a machine credential scoped to one organization. This is the developer path.
2. Session JWTs — the token 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 both can call the same routes. One exception is 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

Create keys 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. You cannot retrieve it again.

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

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

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": "CI pipeline"
6
}'

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 authentication, 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. 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:

The gateway treats an org key as an org-level machine credential. The key passes admin and API-key gates, but it has no user membership. Routes gated on a specific human’s fine-grained resource permission reject a key. Org admins bypass per-resource space checks in all cases.

Session JWTs

The web app’s auth flow mints session JWTs for a signed-in user. They are three-segment JWTs. The platform verifies them against its signing keys. They carry the user’s role, permission claims, and membership id. Do not mint these for server-to-server work. Use an API key instead. This section exists so you recognize them when the web app or an SDK forwards one.

Failure codes

Where to go next