Authentication Methods
API Keys
The primary method for API authentication:
Generate keys in Settings
Include in request headers
Keys are tied to your account
Full access based on your permissions
JWT Tokens
For web applications and OAuth flows:
Obtained through Auth0 login
Short-lived access tokens
Include in Authorization header
Using API Keys
Getting an API Key
Go to Settings > API Keys
Click Create API Key
Name your key (e.g., "Integration Key")
Copy the key immediately
Store it securely
Important: The key is only shown once. If you lose it, create a new one.
Including the Key in Requests
Add the key to the Authorization header:
Authorization: Bearer YOUR_API_KEY
Example Request
curl -X GET "https://app.kaana.com/api/projects" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json"
JWT Token Authentication
Obtaining a Token
For application integrations:
Redirect user to Auth0 login
User authenticates
Receive access token
Use token in requests
Using the Token
Include the JWT in requests:
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Token Expiration
JWT tokens expire after a set period:
Check
expclaim for expirationRefresh tokens before expiry
Re-authenticate if expired
Security Best Practices
Protect Your Keys
Never share API keys
Don't commit keys to code repositories
Use environment variables
Rotate keys periodically
Use HTTPS
Always use HTTPS for API requests:
Encrypts data in transit
Protects your credentials
Required for all endpoints
Least Privilege
Create keys with minimum needed access
Use separate keys for different integrations
Revoke unused keys
Monitor Usage
Review API key activity
Check for unusual patterns
Investigate unexpected usage
Permissions
API access respects your account permissions:
You can only access what you can access in the UI
Tenant isolation is enforced
Admin endpoints require admin role
Error Responses
401 Unauthorized
Your request lacks valid authentication:
{
"error": "Unauthorized",
"message": "Invalid or missing authentication token"
}Solutions:
Check that you included the Authorization header
Verify your API key is correct
Ensure the key hasn't been revoked
403 Forbidden
You don't have permission for this action:
{
"error": "Forbidden",
"message": "You don't have permission to access this resource"
}
Solutions:
Verify you have the required role
Check resource belongs to your tenant
Contact admin for access
Revoking Keys
If a key is compromised:
Go to Settings > API Keys
Find the compromised key
Click Revoke
Create a new key
Update your integrations
Testing Authentication
Verify Your Key Works
curl -X GET "https://app.kaana.com/api/user" \
-H "Authorization: Bearer YOUR_API_KEY"
Expected response:
{"id": 123,
"username": "[email protected]",
"role": "admin"
}
Common Issues
"Invalid token" error:
Check for typos in the key
Ensure no extra spaces
Verify key hasn't been revoked
"Token expired" error:
For JWT: obtain a new token