API authentication

The Seny REST API uses bearer token authentication. Every request must include an Authorization header with a valid API key. All API traffic is HTTPS only.

Base URL

https://app.seny.ai/api/v1

Creating an API key

Open the dashboard and go to Settings → API keys. Click Create API key, give it a label that describes where it will be used (e.g. "production backend"), and copy the key.

The full key is shown only once. Seny stores a hashed version — if you lose it, create a new one and rotate. Keys are scoped to the organization that created them and can access every widget under that org.

Using a key

curl https://app.seny.ai/api/v1/widgets \
  -H "Authorization: Bearer sk_live_abc123..."

Key formats

• sk_live_... — production keys, full access to live data
• sk_test_... — test keys, isolated to sandbox resources (coming soon)

Scopes

API keys are full-access by default. Fine-grained scopes (read-only, single-widget, etc.) are on the roadmap — tell us what you need via Contact.

Rate limits

The API allows up to 600 requests per minute per key. If you exceed the limit you'll get a 429 Too Many Requests response with a Retry-After header. Implement exponential backoff in your client.

Errors

All errors return JSON with a consistent shape:

{
  "error": {
    "code":    "widget_not_found",
    "message": "No widget with id wgt_abc123"
  }
}

HTTP status codes follow REST conventions:

• 200 — success
• 201 — resource created
• 400 — bad request (validation failure)
• 401 — missing or invalid API key
• 403 — authenticated but not authorized
• 404 — resource not found
• 409 — conflict (duplicate)
• 429 — rate limited
• 500 — server error (please retry)

Revoking a key

Delete the key from the Settings → API keys page. It stops working immediately — any in-flight request using it gets a 401 on its next call.