Calling ProjexCloud from your own app

1 · Which credential does your app use?

ProjexCloud accepts two credential classes on its tenant-callable SDK routes. Pick by who is acting.

2 · Generate an API key

Keys are issued by sdk-api-keys, mounted on the gateway. You need two things first: a user JWT (to authorise the issuance) and the tenant_id the key will belong to.

curl -sX POST "$GATEWAY/api/applications" \
  -H "Authorization: Bearer $JWT" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Web backend","environment":"live"}'
# → { "data": { "application": { "application_id": "…", "slug": "web-backend", "environment": "live" } } }

curl -sX POST "$GATEWAY/api/applications/$APPLICATION_ID/keys" \
  -H "Authorization: Bearer $JWT" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "nightly sync",
    "scopes": ["sla.clock.write", "sla.clock.read", "assignment.assign-by-task.write"],
    "rate_limit_rpm": 600,
    "expires_at": "2027-01-01T00:00:00Z"
  }'

{ "data": {
    "key": { "key_id": "…", "tenant_id": "…", "prefix": "pk_live_A1B2...WXYZ",
             "scopes": ["…"], "status": "active" },
    "plaintext": "pk_live_A1B2C3D4E5F6G7H8J9K…"
} }

rate_limit_rpm and expires_at are optional but recommended — an unbounded, never-expiring key is a standing liability. Give every integration its own key so one revocation cannot take down two apps.

Test keys

The format accepts a pk_test_ prefix alongside pk_live_. Issue separate keys for development and production so a leaked dev key can never touch live data.

3 · Scopes

Scopes follow <domain>.<resource>.<action> — for example crm.contact.read, rebac.relationship.write. The scope a request requires is derived from the route itself — on every tenant route, not a subset — so it is predictable without a lookup table, and a route added tomorrow is covered the moment it exists:

A missing scope answers 403 and tells you exactly which one is absent, along with what the key does hold — so the fastest way to discover the scope list you need is to call the endpoint and read the error.

Generated from tests/api_definitions by scripts/verify/gen-scope-table.mjs — 524 endpoints across 90 domains. Do not edit by hand. A domain wildcard such as sla.* covers every row in that domain, including ones added later.

4 · Wire up a development project

Two environment variables and one header. Both a local gateway and the hosted one are supported — the only difference is the base URL and which key you present.

# .env of YOUR application — never commit the key
PROJEXCLOUD_GATEWAY_URL=https://cloud.projexlight.com
PROJEXCLOUD_API_KEY=pk_live_…
PROJEXCLOUD_TENANT_ID=<your-tenant-uuid>
PROJEXCLOUD_TIMEOUT_MS=8000

The request contract

POST {PROJEXCLOUD_GATEWAY_URL}/api/sla/clocks
Authorization:    Bearer {PROJEXCLOUD_API_KEY}   ← the key goes HERE
Content-Type:     application/json
Idempotency-Key:  <stable key per logical operation>
x-correlation-id: <uuid>

{ "tenant_id": "…", "policy_id": "…", "subject_ref": "lead:…" }

Because handlers read tenant_id from the payload, the gateway cross-checks it against the key's own tenant and answers 403 on a mismatch. A leaked key therefore cannot be aimed at another tenant — but it also means the tenant_id you send must be the one the key was issued for.

Supporting both targets from one codebase

Read the base URL from the environment rather than hard-coding it, keep a separate key per target, and let a run-time override win over the committed default. A shell-provided value beats a .env entry with most dotenv loaders, which makes switching a one-command affair:

PROJEXCLOUD_GATEWAY_URL=http://localhost:4000 npm run dev   # local gateway
PROJEXCLOUD_GATEWAY_URL=https://cloud.projexlight.com npm run dev

Two ways to present the credential

Both are supported on every tenant route, and both are checked by the same gate. Pick by volume.

curl "$GATEWAY/api/sla/policies?tenant_id=$TENANT"   -H "Authorization: Bearer $PROJEXCLOUD_API_KEY"

curl -sX POST "$GATEWAY/api/auth/token"   -H 'Content-Type: application/json'   -d '{"grant_type":"client_credentials",
       "client_id":"web-backend",
       "client_secret":"'"$PROJEXCLOUD_API_KEY"'"}'
# → { "access_token":"eyJ…", "token_type":"Bearer",
#      "expires_in":900, "scope":"sla.clock.read sla.clock.write" }

5 · Rotate and revoke

Rotation without downtime: rotate → deploy the new key → confirm traffic on the new prefix via last_used_at → revoke the old key. Skipping the final revoke leaves a live credential in the wild after the grace window ends.

Every issuance, rotation and revocation emits an audit event (api-key.issued.v1, api-key.rotated.v1, api-key.revoked.v1), so key custody is reviewable after the fact.

6 · Troubleshooting

← Developer Hub API reference: api-keys ↗ Agent Cookbook ↗