Skip to main content
Every authenticated endpoint requires a Bearer token in the Authorization header: 
curl "$API_BASE/api/v1/connections" \
 -H "Authorization: Bearer $API_KEY"

​
Key modes

Structural uses three API key modes, distinguished by prefix:
PrefixModeHow to get one
sk_demo_SandboxInstantly via POST /api/v1/demo/session
sk_test_StagingIssued during customer onboarding - email [email protected]
sk_live_ProductionIssued during customer onboarding - email [email protected]
All three modes go through identical Bearer authentication. The prefix tells you which environment the key targets, not a difference in behavior or permissions.

​
Key lifecycle

  • Keys are SHA-256 hashed at rest and returned exactly once at creation. There is no retrieval endpoint - capture your key immediately.
  • Demo keys (sk_demo_*) are ephemeral. They are revoked when you call DELETE /api/v1/demo/session.
  • Production and staging keys (sk_live_*, sk_test_*) are provisioned during customer onboarding by the Structural team.

​
Error responses

Missing or invalid keys return 401: 
{
  "error": {
    "type": "AUTHENTICATION_ERROR",
    "message": "Invalid or missing API key",
    "request_id": "req_a1b2c3d4e5f6"
  }
}

​
Rate limits

POST /api/v1/demo/session is rate-limited to 5 requests per IP per minute. Exceeding this returns 429 RATE_LIMIT_ERROR. Other endpoints have no enforced rate limit today, but usage is subject to fair-use expectations. Sustained high-volume usage requires a production key with limits negotiated during customer onboarding.

​
CORS

The API restricts allowed origins via a server-side CORS_ORIGIN configuration. Browser consumers should expect CORS preflights to fail unless their origin is whitelisted. To get your domain added to the allowed origins list, contact [email protected] during onboarding.

​
Content-Type

All non-GET requests must include Content-Type: application/json. Requests with a different Content-Type receive a 415 UNSUPPORTED_MEDIA_TYPE error before reaching the route handler. Every curl example in these docs includes the header explicitly.

​
Response headers

Every response includes:
HeaderDescription
X-Request-IDUnique request identifier (e.g., req_a1b2c3d4e5f6). Quote this in support requests.
API-VersionCurrent API version (e.g., 1.0).