Authentication
API keys, request headers, environments, rate limits, and error codes.
Last updated
API keys, request headers, environments, rate limits, and error codes.
Every API and SDK call is authenticated with an API key created in the admin panel. User-scoped calls add a user header, and browser embeds use a short-lived embed token instead of the key.
Send the key in the x-api-key header on every request:
x-api-key: <motif-api-key>Keys must be created through the admin panel. A key created directly in the underlying auth provider won't work. SDK and API access requires the key to be linked to an organization, which only the admin panel does. See API keys to create, rotate, and revoke keys.
The API key is an organization-wide secret. Never expose it in client-side code. For browser integrations, mint an embed token server-side instead.
Operations scoped to a specific end user (profiling, strategies) also require the x-user-id header:
x-api-key: <motif-api-key>
x-user-id: <motif-user-id>The user must belong to the same organization as the API key. The SDK sets this header for you when you call motif.forUser(userId).
The Clarity iframe authenticates with a short-lived x-embed-token instead of the API key, so the key never reaches the browser. You mint the token server-side and hand only the token to the page. See Embed Clarity.
Production
https://api.motifapp.ai/api (SDK default)
Production keys, from a production organization
Staging
https://staging.backend.motifapp.ai/api
Staging keys, from the staging dashboard
Override the SDK baseURL only when targeting staging or local development. Use sandbox or staging organizations for development and automated tests, never production keys.
API keys are rate-limited with a daily request window by default. If you need higher production limits, contact Motif.
Authentication and authorization failures use standard HTTP status codes, surfaced by the SDK as MotifSDKError:
400
Missing x-user-id on a user-scoped call, or invalid input
401
Missing or invalid x-api-key / x-embed-token
403
Key not linked to an organization, organization inactive, or cross-organization access
404
Target resource (user, portfolio, strategy) not found
429
Rate limit exceeded
See Error handling for handling patterns.
Store keys in a secrets manager or environment variables, never in source control or the browser.
Use separate keys per environment and per service.
Rotate by creating a replacement key, updating your backend, then disabling the old key.
Revoke immediately if a key is compromised. Every mutation is logged for auditing.
Last updated
x-embed-token: <short-lived-jwt>