# API Keys
## Overview
**API keys** (Personal Access Tokens) let you authenticate with the Kognitos REST API. Each key is scoped to specific workspaces and permissions, giving you control over what API consumers can access.
## Creating an API Key
{% stepper %}
{% step %}
**Open API Keys**
Click on your name or profile avatar in the bottom-left corner to open the user menu. Then select **API Keys**.
{% endstep %}
{% step %}
**Create a New Key**
Click **Create API Key**. Fill in the following:
* **Name**: A descriptive name (e.g., "CI Pipeline", "Monitoring Dashboard")
* **Expiration**: How long the key is valid (7 days, 30 days, 60 days, 90 days, 180 days, or 1 year)
* **Scope**: Which workspaces the key can access
* **Permissions**: What the key can do
{% endstep %}
{% step %}
**Choose Permissions**
Select a permission level:
| Permission | Access |
| -------------- | --------------------------------------------------------------------------------------------- |
| **All** | Full read and write access to all API endpoints, including run archiving |
| **Read only** | Read access only (list, get, query endpoints) |
| **Restricted** | Custom per-resource permissions (includes granular control over run management and archiving) |
{% hint style="info" %}
When selecting **Restricted**, you can expand each permission group and toggle individual permissions on or off.
{% endhint %}
{% endstep %}
{% step %}
**Set the Scope**
Choose which workspaces this key can access:
* **All Workspaces**: Access to every workspace in the organization
* **Specific Workspaces**: Select one or more workspaces from the list
{% endstep %}
{% step %}
**Save Your Key**
Click **Create**. Your API key will be displayed once. Copy it and store it securely.
{% hint style="warning" %}
**Save your key now.** You will not be able to view it again. If you lose it, you will need to create a new one.
{% endhint %}
{% endstep %}
{% endstepper %}
## Using Your API Key
Include the key in the `Authorization` header of every API request:
```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.us-1.kognitos.com/api/v1/me/organizations"
```
## Managing API Keys
From the **API Keys** page, you can view all keys with their name, key prefix, scope, and creation date.
Use the menu on each row to **edit** a key's name, permissions, or scope, or **delete** a key to immediately revoke access.
{% hint style="warning" %}
Deleting an API key immediately disables it. Any systems using that key will lose access.
{% endhint %}
## Limits
* Up to **10 API keys** per organization
* Keys are scoped to the **organization** where they were created
* Expired keys are automatically disabled
## Best Practices
* **Use descriptive names** so you know which system uses each key
* **Set the shortest expiration** that meets your needs
* **Use restricted permissions** to limit access to only what each consumer needs
* **Rotate keys regularly** by creating a new key before deleting the old one
* **Never commit keys to source control**. Use environment variables or a secrets manager.
