Moving from the organization API key

The organization API key stops working 90 days after the API launches

The API opens when api.tradecrafthub.ai launches. 90 days later, requests with the x-api-key header answer 401 UNAUTHENTICATED, and the stored keys are then deleted. The exact date is set at the launch: it appears in the Sunset header, in Admin → API, and in an email to the admins of organizations that used the key in the last 30 days. Move your scripts to a machine client before then; if 90 days is too little time, contact us.

Until now, scripts could call the web app’s own routes (/{organization}/api/v1/…) with one shared organization key in the x-api-key header. That key is deprecated:

• Every response to it carries Deprecation and Link: <https://tradecrafthub.ai/docs/api/migrate-from-api-key/>; rel="deprecation" (this page). From the launch it also carries Sunset: <launch + 90 days>, the date the key stops working.
• Each use is recorded in the audit log (legacy_api_key_used).
• Admin → API → Settings shows The organization API key is deprecated, with when it was last used and when it stops working (90 days after the launch; the date once the API has launched).
• The key acts as a member with the User role only, and only for reads plus uploading, Analyze, Process and asking a question. It is never accepted on api.tradecrafthub.ai.

Move a script in four steps

1. Turn the API on: Admin → API → Settings → Allow the Tradecraft API.
2. Create a machine client in Admin → API → Clients → New API client → Machine client. Pick the acting role and the scopes the script needs (table below). Store the client secret where the old key was.
3. Get a token with client credentials and send it as Authorization: Bearer …. Tokens last an hour: request a new one when it expires.
4. Change the URLs to https://api.tradecrafthub.ai/v1/…. Your organization is no longer in the path: it comes from the token.

# Before
curl -s -H "x-api-key: $TRADECRAFT_KEY" "https://tradecraft.m11solutions.com/acme/api/v1/assessments"

# After
TOKEN=$(curl -s -u "$CLIENT_ID:$CLIENT_SECRET" -d grant_type=client_credentials \
  https://api.tradecrafthub.ai/oauth/token | jq -r .access_token)
curl -s -H "Authorization: Bearer $TOKEN" "https://api.tradecrafthub.ai/v1/assessments"

// Before: fetch(`https://tradecraft.m11solutions.com/acme/api/v1/assessments`, { headers: { "x-api-key": key } })
const token = await getToken() // client credentials, see Machine clients
const res = await fetch("https://api.tradecrafthub.ai/v1/assessments", { headers: { Authorization: `Bearer ${token}` } })

Where each call goes

Paths with the key were /{organization}/api/v1/…; on the API they are /v1/….

• GET /assessments → GET /v1/assessments (assessments:read)
• GET /assessments/{id} → GET /v1/assessments/{id} and GET /v1/assessments/{id}/questions (assessments:read)
• GET /assessments/{id}/download → GET /v1/assessments/{id}/download (assessments:read)
• POST /assessments → POST /v1/assessments, with an Idempotency-Key (assessments:write)
• POST /assessments/{id}/analyze → POST /v1/assessments/{id}/analyze, with an Idempotency-Key (assessments:write)
• POST /assessments/{id}/process → POST /v1/assessments/{id}/process, with an Idempotency-Key (assessments:write)
• POST /security-center/ask → POST /v1/ask (knowledge:ask)
• GET /knowledge/answers → GET /v1/answers (knowledge:read)

What is different

• Responses have their own, stable shapes. Check the fields your script reads against the reference; the web app’s routes could change at any time, the API’s cannot (Versioning).
• Lists use cursors (limit, cursor, meta.nextCursor) instead of pages: see Pagination.
• Uploads and runs need an Idempotency-Key, which makes retries safe: see Idempotency.
• Which assessments a client sees depends on its acting role. Like the key, a User client sees only the questionnaires it uploaded itself, so it will not see what the key uploaded. Choose Reviewer if the script must see every questionnaire.
• Rate limits apply and are reported in RateLimit-* headers: see Rate limits.