# 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

{% stepper %}
{% step %}
Go to **Settings** > **API Keys**
{% endstep %}

{% step %}
Click **Create API Key**
{% endstep %}

{% step %}
Name your key (e.g., "Integration Key")
{% endstep %}

{% step %}
Copy the key immediately
{% endstep %}

{% step %}
Store it securely
{% endstep %}
{% endstepper %}

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

{% stepper %}
{% step %}
Redirect user to Auth0 login
{% endstep %}

{% step %}
User authenticates
{% endstep %}

{% step %}
Receive access token
{% endstep %}

{% step %}
Use token in requests
{% endstep %}
{% endstepper %}

### 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

<details>

<summary>401 Unauthorized</summary>

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

</details>

<details>

<summary>403 Forbidden</summary>

```
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

</details>

## Revoking Keys

If a key is compromised:

{% stepper %}
{% step %}
Go to **Settings** > **API Keys**
{% endstep %}

{% step %}
Find the compromised key
{% endstep %}

{% step %}
Click **Revoke**
{% endstep %}

{% step %}
Create a new key
{% endstep %}

{% step %}
Update your integrations
{% endstep %}
{% endstepper %}

## 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": "you@example.com",
  "role": "admin"
}
```

## Common Issues

<details>

<summary>"Invalid token" error</summary>

* Check for typos in the key
* Ensure no extra spaces
* Verify key hasn't been revoked

</details>

<details>

<summary>"Token expired" error</summary>

* For JWT: obtain a new token

</details>