API Authentication

Learn how to authenticate your API requests.

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

1

Go to Settings > API Keys

2

Click Create API Key

3

Name your key (e.g., "Integration Key")

4

Copy the key immediately

5

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

1

Redirect user to Auth0 login

2

User authenticates

3

Receive access token

4

Use token in requests

Using the Token

Include the JWT in requests:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiration

• Check exp claim for expiration

• Refresh 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

{
  "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:

1

Go to Settings > API Keys

2

Find the compromised key

3

Click Revoke

4

Create a new key

5

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": "[e-mail]",
  "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