API Authentication
Secure your API requests with API keys or OAuth 2.0 tokens. Learn best practices for managing credentials and securing integrations.
Authentication Methods
API Keys
Long-lived tokens for server-to-server integrations. Best for backend services and automation scripts.
OAuth 2.0 Tokens
Short-lived tokens obtained via OAuth flow. Best for user-facing applications that act on behalf of users.
Using API Keys
Include your API key in the Authorization header:
curl https://api.accessiq.io/v1/organizations/YOUR_ORG/users \
-H "Authorization: Bearer ak_live_abc123xyz789"Creating API Keys
curl -X POST https://api.accessiq.io/v1/organizations/YOUR_ORG/api-keys \
-H "Authorization: Bearer YOUR_EXISTING_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Production Backend",
"permissions": ["users:read", "users:write", "roles:read"],
"expiresIn": "365d"
}'
# Response
{
"id": "key_abc123",
"name": "Production Backend",
"key": "ak_live_abc123xyz789...",
"permissions": ["users:read", "users:write", "roles:read"],
"createdAt": "2024-01-15T10:00:00Z",
"expiresAt": "2025-01-15T10:00:00Z"
}API Key Types
| Prefix | Environment | Use Case |
|---|---|---|
ak_live_ | Production | Live production data and operations |
ak_test_ | Sandbox | Testing and development |
scim_ | SCIM | SCIM provisioning integrations |
API Key Permissions
Scope API keys to specific permissions using fine-grained access control:
{
"permissions": [
// Users
"users:read", // Read user data
"users:write", // Create/update users
"users:delete", // Delete users
// Organizations
"organizations:read", // Read org data
"organizations:write", // Update org settings
// Roles & Permissions
"roles:read", // Read roles
"roles:write", // Manage roles
// Identity Providers
"idp:read", // Read IdP config
"idp:write", // Manage IdPs
// Audit Logs
"audit:read", // Read audit logs
// Webhooks
"webhooks:read", // Read webhook config
"webhooks:write" // Manage webhooks
]
}OAuth 2.0 Authentication
For applications acting on behalf of users, use OAuth 2.0 Authorization Code flow:
Step 1: Redirect to Authorization
https://auth.accessiq.io/oauth/authorize?
client_id=YOUR_CLIENT_ID&
redirect_uri=https://your-app.com/callback&
response_type=code&
scope=openid profile email&
state=random_state_stringStep 2: Exchange Code for Token
curl -X POST https://auth.accessiq.io/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=AUTH_CODE_FROM_CALLBACK" \
-d "redirect_uri=https://your-app.com/callback" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET"
# Response
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "rt_abc123...",
"scope": "openid profile email"
}Step 3: Use Access Token
curl https://api.accessiq.io/v1/users/me \
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."Token Refresh
Use refresh tokens to obtain new access tokens without user interaction:
curl -X POST https://auth.accessiq.io/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=rt_abc123..." \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET"Security Best Practices
Use Environment Variables
Store API keys in environment variables, never in code. Use a secrets manager for production deployments.
Rotate Keys Regularly
Rotate API keys every 90 days. AccessIQ supports overlapping validity periods for zero-downtime rotation.
Least Privilege
Only grant the permissions your integration needs. Create separate keys for different services.
Monitor Usage
Review API key usage in the dashboard. Set up alerts for unusual activity patterns.
Revoking API Keys
curl -X DELETE https://api.accessiq.io/v1/organizations/YOUR_ORG/api-keys/key_abc123 \
-H "Authorization: Bearer YOUR_API_KEY"
# Response: 204 No Content