Authentication

KAPEX uses API key authentication. Every request (except trial signup and health checks) must include a valid API key in the X-API-Key header.

Using Your API Key

Include the X-API-Key header on every request:

curl -X POST https://api.getkapex.ai/api/v1/query \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "user_001", "current_input": "How is the project going?"}'

import requests

headers = {
    "X-API-Key": "your_api_key_here",
    "Content-Type": "application/json"
}

resp = requests.post(
    "https://api.getkapex.ai/api/v1/query",
    headers=headers,
    json={"user_id": "user_001", "current_input": "How is the project going?"}
)

Trial Signup Flow

1. Create a Trial Account

The signup endpoint is the only endpoint that does not require authentication.

curl -X POST https://api.getkapex.ai/api/v1/trial/signup \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Health",
    "email": "dev@acmehealth.com",
    "name": "Jordan Park"
  }'

2. Receive Your API Key

The response includes your API key. This is the only time the key is returned -- store it immediately in a secure location.

{
  "status": "trial_active",
  "tenant_id": "tn_acme_health_01",
  "api_key": "a1b2c3d4e5f6g7h8i9j0",
  "trial_ends": "2026-07-18T00:00:00Z",
  "limits": {
    "max_users": 25,
    "max_nodes_per_user": 5000,
    "rate_limit_rpm": 60,
    "rate_limit_daily": 10000,
    "features": "all"
  }
}

3. Start Making Requests

Use the key in the X-API-Key header for all subsequent API calls.

Trial Limits

All KAPEX features are available during the trial period with no restrictions beyond user count and rate limits.

Trial Expiration

The X-Trial-Days-Remaining header is included in every API response during the trial period.

HTTP/1.1 200 OK
Content-Type: application/json
X-Trial-Days-Remaining: 22

When the trial expires:

• All API requests return 403 Forbidden with the error code TRIAL_EXPIRED.
• Stored data is retained for 30 days after trial expiration to allow migration.
• Contact support@sandstonecloud.com to upgrade to a paid plan.

{
  "error": {
    "code": "TRIAL_EXPIRED",
    "message": "Your trial expired on 2026-07-18. Contact support@sandstonecloud.com to continue."
  }
}

Rate Limits

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1750320000

When Rate Limited

When you exceed the rate limit, the API returns 429 Too Many Requests with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 12

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 12 seconds."
  }
}

Wait the number of seconds specified in Retry-After before retrying.

Security Best Practices

Do

• Transmit API keys only over HTTPS. KAPEX rejects plaintext HTTP connections.
• Store keys in environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault).
• Use separate API keys for development and production environments.
• Rotate keys periodically by contacting support.

Do Not

• Include API keys in URLs as query parameters. Keys belong in the X-API-Key header only.
• Commit API keys to version control. Add your .env file to .gitignore.
• Share API keys across teams. Each team or service should have its own key.
• Log API keys in application logs or error reporting tools.

Example: Loading from Environment Variable

import os
import requests

api_key = os.environ["KAPEX_API_KEY"]

headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

resp = requests.post(
    "https://api.getkapex.ai/api/v1/query",
    headers=headers,
    json={"user_id": "user_001", "current_input": "How is the project going?"}
)

# .env (add to .gitignore)
KAPEX_API_KEY=your_api_key_here

Error Codes

401 Unauthorized

Returned when the X-API-Key header is missing or the key is not recognized.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key. Include a valid key in the X-API-Key header."
  }
}

403 Forbidden

Returned when the key is valid but access is denied. The most common cause is an expired trial.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Trial expired. Contact support@sandstonecloud.com to upgrade."
  }
}

429 Rate Limited

Returned when you exceed your tier's per-minute or per-day request limit.

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 12 seconds."
  }
}

Endpoints That Do Not Require Authentication

All other endpoints require a valid X-API-Key header.

Support

For API key issues, trial extensions, or to upgrade to a paid plan, contact support@sandstonecloud.com.