API Authentication

This guide covers how to authenticate with the CICosts API.

API Keys

All API requests require an API key for authentication.

Generating a Key

1. Go to Settings → API
2. Click Generate API Key
3. Give it a descriptive name
4. Click Create
5. Copy the key immediately - it's only shown once

Key Format

API keys are prefixed for easy identification:

cic_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

• cic - CICosts prefix
• live - Production key (vs test)
• xxxx... - Unique key value

Using Your Key

Include the API key in the Authorization header:

curl -H "Authorization: Bearer cic_live_xxxxxxxxxxxx" \
  https://api.cicosts.dev/v1/costs

Key Management

Viewing Keys

View all your API keys at Settings → API:

• Key name
• Created date
• Last used
• Permissions

Note: The actual key value is not shown after creation.

Revoking Keys

To revoke a key:

1. Go to Settings → API
2. Find the key
3. Click Revoke
4. Confirm

Revoked keys stop working immediately.

Key Rotation

Rotate keys periodically for security:

1. Create a new key
2. Update your applications
3. Revoke the old key

We recommend rotating keys every 90 days.

Key Permissions

API keys can have scoped permissions:

Permission	Description
costs:read	Read cost data
workflows:read	Read workflow data
alerts:read	Read alerts
alerts:write	Create/update/delete alerts
webhooks:write	Manage webhooks

Creating Scoped Keys

When generating a key:

1. Click Advanced Options
2. Select only needed permissions
3. Create the key

Example: A reporting integration only needs costs:read.

Security Best Practices

Never Expose Keys

• Don't commit keys to version control
• Don't include in client-side code
• Use environment variables

# Good - environment variable
export CICOSTS_API_KEY=cic_live_xxxx
curl -H "Authorization: Bearer $CICOSTS_API_KEY" ...

# Bad - hardcoded
curl -H "Authorization: Bearer cic_live_xxxx" ...

Use Least Privilege

Only grant permissions that are needed:

• Reporting: costs:read only
• Alert automation: alerts:read,alerts:write
• Full integration: all permissions

Monitor Key Usage

Regularly review:

• Which keys are active
• When they were last used
• Revoke unused keys

Secure Storage

Store keys in:

• Environment variables
• Secret managers (AWS Secrets Manager, HashiCorp Vault)
• CI/CD secret storage (GitHub Secrets)

Never store in:

• Plain text files
• Logs
• Email
• Chat messages

Authentication Errors

Invalid Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid"
  }
}

Solution: Check that the key is correct and hasn't been revoked.

Expired Key

{
  "error": {
    "code": "expired_api_key",
    "message": "This API key has expired"
  }
}

Solution: Generate a new key.

Insufficient Permissions

{
  "error": {
    "code": "insufficient_permissions",
    "message": "This API key does not have permission for this action"
  }
}

Solution: Generate a new key with appropriate permissions.

Missing Key

{
  "error": {
    "code": "missing_authorization",
    "message": "Authorization header is required"
  }
}

Solution: Include the Authorization: Bearer <key> header.

OAuth (Coming Soon)

For user-facing integrations, we'll support OAuth 2.0:

• Authorization code flow
• Refresh tokens
• Scoped permissions

Contact us if you need OAuth for your integration.

---

Next: Costs Endpoint →