Skip to main content

Authentication

Use this page after Getting Started. The first request flow lives there; this page focuses on how External API credentials behave and how to handle them safely.

Required Headers​

Every External API request must include both headers:

X-Api-Key: <api-key>
X-Org-Id: <organization-id>

X-Api-Key identifies the calling integration. X-Org-Id scopes the request to one Siesta AI organization. A valid key without the matching organization context will still fail for resources outside that scope.

The interactive reference uses placeholders in code samples. Replace them in your backend or local test tool. Do not expose production API keys in frontend code.

Trusted Execution Only​

Use API keys only from trusted server-side code:

  • backend route handlers;
  • scheduled jobs;
  • internal integration services;
  • local development tools.

Do not place API keys in:

  • browser bundles or static sites;
  • mobile apps distributed to end users;
  • screenshots, tickets, or shared chat messages;
  • logs, analytics events, or client-side error reporting;
  • public repositories or checked-in config files.

If you need browser-based behavior, send the request through your own backend and inject the Siesta AI credentials there.

Key Storage And Rotation​

Store the API key in a secret manager or environment variable controlled by your backend deployment. Keep X-Org-Id alongside the integration configuration so each environment points to the correct organization.

Recommended setup:

  1. Keep production and non-production keys separate.
  2. Use one integration identity per environment or app surface when possible.
  3. Rotate keys by updating the backend secret first, then re-testing a read-only endpoint.
  4. Remove unused keys when an integration is retired.

Testing From The Docs​

The API reference includes an inline Try request section for quick testing. Values entered there are kept in the browser session and are not committed to the docs repository or placed in the page URL.

Use that mode only for controlled local validation. If browser policy, company network rules, or CORS settings prevent the request from being sent from the docs domain, use the generated curl command instead.

Common Status Codes​

  • 401 Unauthorized: missing, expired, or invalid API key.
  • 403 Forbidden: the key is valid but does not have access to the resource or organization.
  • 404 Not Found: the resource does not exist or is not visible to the current organization.
  • 429 Too Many Requests: the client is sending requests too quickly.

Review the response section for each endpoint in the External API Reference for exact documented response shapes.