Authentication

IceCore API uses API keys for authentication.

Creating API Keys

Dashboard: Settings → API Keys → Create API Key

Request:

POST /api/api-keys
Content-Type: application/json

{
  "workspaceId": "uuid",
  "name": "Production API Key",
  "mode": "live",
  "permissions": {
    "read": true,
    "write": true,
    "conversations": true,
    "analytics": true,
    "bulk_send": true
  },
  "expiresInDays": 365,
  "rateLimitPerMinute": 100
}

Mode Options:

• live: Production API key (format: sk_live_...)

• test: Development/testing API key (format: sk_test_...)

Note: Default is live if not specified.

Response:

{
  "key": "sk_live_a1b2c3d4e5f6...",
  "keyData": {
    "id": "key_uuid",
    "key_prefix": "sk_live_...",
    "permissions": {...}
  },
  "warning": "Save this key securely. You won't be able to see it again!"
}

⚠️ Important: The full API key is shown only once. Store it securely!

Using API Keys

Include the API key in the Authorization header:

curl https://icecore.ai/api/v1/conversations \
  -H "Authorization: Bearer sk_live_a1b2c3d4e5f6..."

Key Types

Permissions

Rate Limits

API keys have configurable rate limits:

Headers returned:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1635724800

When exceeded: 429 Too Many Requests

Security Best Practices

1. Never commit keys to version control

2. Use environment variables

3. Rotate keys regularly (every 90 days recommended)

4. Use minimum permissions needed

5. Set expiration dates for keys

Managing Keys

List Keys

GET /api/api-keys?workspaceId={id}

Deactivate Key

PATCH /api/api-keys
{
  "workspaceId": "uuid",
  "keyId": "key_uuid",
  "isActive": false
}

Delete Key

DELETE /api/api-keys?workspaceId={id}&keyId={key_id}

Error Responses

401 Unauthorized

{
  "error": "Invalid or expired API key"
}

429 Rate Limit Exceeded

{
  "error": "Rate limit exceeded",
  "retry_after": 30
}

Next: REST API Reference