Skip to main content
Every request to the Shilo API must include a valid API key. Keys are scoped to your organization and carry either read-only or read-write permissions, so you can issue tightly scoped credentials to third-party tools without granting unnecessary access.

​
Generating an API Key

API keys are created in the Shilo web app. You must be an owner or admin to generate them.
  1. Open Settings in the Shilo app.
  2. Navigate to API Keys.
  3. Click Create API Key, give it a descriptive name, and choose its permission level.
  4. Copy the key immediately—it will not be shown again.

​
Sending Your API Key

You can authenticate using either of two header formats. Both are accepted on every endpoint.

​
Option 2 — Authorization: Bearer header

Both headers carry the same key value. Use whichever format fits your HTTP client or SDK most naturally.

​
Read-Only vs. Read-Write Keys

Shilo issues two permission tiers: A read-only key attempting a write operation receives a 403 Forbidden response. This lets you safely hand a key to a reporting dashboard or analytics pipeline without risking accidental data changes.

​
Error Responses

A 401 response typically means the key was not included in the header, was mistyped, or has been revoked. Double-check both the header name and the key value.

​
Complete Authentication Example

The following request lists your organization’s users using the x-api-key header:
The same request using the Authorization header:
Keep your API keys secret. Never embed them in client-side JavaScript, mobile app binaries, or public repositories. Store keys in environment variables or a secrets manager, and rotate them regularly to limit exposure if a key is compromised.

​
Security Best Practices

  • Use separate keys per integration. Isolate credentials so you can revoke a single key without disrupting other systems.
  • Prefer read-only keys for any integration that only needs to read data.
  • Rotate keys periodically. Generate a replacement key, update your integration, then delete the old key.
  • Audit key usage. Check the Shilo Settings page regularly for keys that are no longer in use and revoke them.