Authentication

Secure your API requests with proper authentication.

API Keys

Creating an API Key

1. Go to Settings → Security → API Keys
2. Click Generate New Key
3. Name your key (e.g., "Production App")
4. Select permissions
5. Set expiration (optional)
6. Click Create
7. Copy and store the key securely

warning

API keys are shown only once. Store them securely immediately.

Using API Keys

Include in the Authorization header:

curl -X GET \
  https://api.ivertonai.com/v1/clients \
  -H "Authorization: Bearer YOUR_API_KEY"

Key Permissions

Scope	Description
read:clients	Read client data
write:clients	Create/update clients
read:contacts	Read contacts
write:contacts	Create/update contacts
read:campaigns	Read campaigns
write:campaigns	Manage campaigns
read:analytics	Access analytics
admin	Full access

Revoking Keys

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

OAuth 2.0

For user-authorized integrations, use OAuth 2.0.

Authorization Flow

1. Redirect to Authorization

GET https://auth.ivertonai.com/oauth/authorize
  ?client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=read:clients write:contacts
  &state=random_state_string

2. Exchange Code for Token

POST https://auth.ivertonai.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://yourapp.com/callback

3. Response

{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
  "scope": "read:clients write:contacts"
}

Refreshing Tokens

POST https://auth.ivertonai.com/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=YOUR_REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

OAuth Scopes

Scope	Description
openid	OpenID Connect
profile	User profile info
email	User email
read:*	Read access to resource
write:*	Write access to resource
offline_access	Refresh tokens

Security Best Practices

Do's

• Store keys in environment variables
• Use minimal required scopes
• Rotate keys regularly
• Use HTTPS always
• Implement key expiration

Don'ts

• Never commit keys to version control
• Don't share keys between environments
• Don't expose keys in client-side code
• Don't log full API keys

Environment Variables

# .env file (never commit!)
IVERTON_API_KEY=sk_live_xxxxxxxxxxxxx

// Usage
const apiKey = process.env.IVERTON_API_KEY;

Error Codes

Code	Description
INVALID_API_KEY	API key is invalid
EXPIRED_API_KEY	API key has expired
INSUFFICIENT_SCOPE	Missing required permissions
RATE_LIMITED	Too many requests

---

Next: API Endpoints →