> ## Documentation Index
> Fetch the complete documentation index at: https://noorle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Generate and manage API keys for service account authentication. Understand API key format and security.

API Keys are long-lived credentials for authenticating with the Noorle API. Use them for integrations, automation, and backend services.

<Info>
  **Why are API keys managed under Service Accounts?** API keys are now organized under Service Accounts so you can group related keys, assign granular permissions per service, and rotate or revoke keys without affecting other integrations. You can still create [direct (personal) keys](#direct-api-keys) for quick development — but for production workloads, Service Account keys give you better security and auditability.
</Info>

For a conceptual overview of API keys, see [API Keys in Learn](/learn/auth/api-keys).

## API Key Format

```
ak-{access_id}{secret}
```

* **`ak-`** prefix identifies the string as an API key
* **Access ID** — 32 hex characters (UUID without hyphens), public identifier
* **Secret** — private credential appended directly after the access ID

<Warning>
  API keys are shown only once at creation. Store them immediately in a secure location.
</Warning>

## Generating API Keys

### Service Account Keys

The primary method. API keys are automatically generated when you create a service account:

1. Go to **Team** > **Service Accounts**
2. Click **Create Service Account**
3. Fill in name, description, role
4. Click **Create**
5. Copy the displayed API key immediately

To create additional keys for the same service account:

1. Go to **Team** > **Service Accounts** > Select account
2. Click **API Keys** tab
3. Click **Generate New Key**
4. Copy and store securely

You can have multiple active keys per service account for rotation scenarios.

### Direct API Keys

For personal development and quick integrations:

1. Go to **Settings** > **API Keys**
2. Click **Create API Key**
3. Set a name, scope, and permissions
4. Click **Create**
5. Copy the displayed API key immediately

Direct keys are tied to your user account rather than a service account.

## Using API Keys

### Authentication Header

Include your API key in the `X-API-Key` header:

```bash theme={null}
curl https://api.noorle.com/v1/agents \
  -H "X-API-Key: ak-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4s9t0u1v2w3x4y5z6"
```

### Environment Variable

Store your key in an environment variable:

```bash theme={null}
export NOORLE_API_KEY="ak-a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4s9t0u1v2w3x4y5z6"

curl https://api.noorle.com/v1/agents \
  -H "X-API-Key: $NOORLE_API_KEY"
```

### In Application Code

**JavaScript:**

```javascript theme={null}
const response = await fetch('https://api.noorle.com/v1/agents', {
  headers: {
    'X-API-Key': process.env.NOORLE_API_KEY
  }
});
```

**Python:**

```python theme={null}
import requests
import os

headers = {
    'X-API-Key': os.environ['NOORLE_API_KEY']
}
response = requests.get('https://api.noorle.com/v1/agents', headers=headers)
```

**Go:**

```go theme={null}
req, _ := http.NewRequest("GET", "https://api.noorle.com/v1/agents", nil)
req.Header.Add("X-API-Key", apiKey)
client := &http.Client{}
response, _ := client.Do(req)
```

## Managing API Keys

### View All Keys

1. Go to **Team** > **Service Accounts** > Select account
2. Click **API Keys** tab
3. See all active keys with:
   * Last 6 characters (for identification)
   * Creation date
   * Last used date
   * Status (Active/Revoked)

### Rotate Keys

Replace an active key with a new one:

<Steps>
  <Step title="Generate New Key">
    Click **Generate New Key** and copy it.
  </Step>

  <Step title="Update Applications">
    Update all applications and scripts to use the new key.
  </Step>

  <Step title="Verify New Key Works">
    Test the new key in your application:

    ```bash theme={null}
    curl https://api.noorle.com/v1/agents \
      -H "X-API-Key: {new_key}"
    ```
  </Step>

  <Step title="Revoke Old Key">
    In the API Keys tab, click **Revoke** on the old key.
  </Step>

  <Step title="Monitor for Old Key Usage">
    Check activity logs to ensure no old key usage within 24 hours.
  </Step>
</Steps>

### Revoke Keys

Instantly disable a key without deleting the service account:

1. Go to **Team** > **Service Accounts** > Select account
2. Click **API Keys** tab
3. Find the key you want to revoke
4. Click **Revoke**
5. Confirm revocation

Revoked keys will return `401 Unauthorized` on all API calls. This is immediate.

### Delete Keys

Permanently remove a key (only possible after revocation):

1. Revoke the key first
2. Wait 24 hours (safety period)
3. Click **Delete**
4. Confirm deletion

This is irreversible.

## API Key Security

### Storage Best Practices

**Do NOT:**

* Hardcode keys in source code
* Store in version control (git, etc.)
* Share via email or chat
* Store in plain text config files
* Log or expose in error messages

**DO:**

* Store in environment variables
* Use a secret manager (e.g., HashiCorp Vault, 1Password)
* Encrypt at rest if stored on disk
* Restrict file permissions (chmod 600)
* Use `.gitignore` to exclude credential files

### Secret Manager Examples

**GitHub Secrets:**

```yaml theme={null}
env:
  NOORLE_API_KEY: ${{ secrets.NOORLE_API_KEY }}
```

**Environment Variable:**

```bash theme={null}
export NOORLE_API_KEY="ak-..."
```

**HashiCorp Vault:**

```bash theme={null}
vault kv get secret/noorle/api-key
```

**Secret Manager:**

```bash theme={null}
# Retrieve from your secret manager
```

### Least Privilege

* Create separate service accounts for different purposes
* Assign only required role and resource restrictions
* Use Viewer role for read-only access
* Use Developer role for resource creation/modification

### Monitoring

Enable audit logging to track API key usage:

1. Go to **Team** > **Service Accounts** > Select account
2. View **Activity** tab
3. Monitor for:
   * Unexpected API calls
   * Failed authentication attempts
   * Access from unusual IP addresses or times
   * Unusual data access patterns

## Troubleshooting

### "Invalid API Key" Error

**Check:**

* Key format is correct (`ak-` prefix)
* Key hasn't been revoked
* Key hasn't been deleted
* No extra whitespace in the header

**Test:**

```bash theme={null}
curl https://api.noorle.com/v1/agents \
  -H "X-API-Key: ak-{your_key}" \
  -v  # Show headers for debugging
```

### "Unauthorized" (401) Error

The key is valid but doesn't have permission:

1. Check service account role (Developer or higher needed)
2. Verify resource isn't restricted to other accounts
3. Ensure service account isn't disabled

### Key Stops Working After Rotation

Old key was revoked before all applications updated:

1. Generate a new key
2. Update remaining applications
3. Monitor logs for any old key usage
4. If critical, create new service account as backup

### Lost API Key

**If compromised:**

1. Revoke the key immediately
2. Generate a new key
3. Update all applications
4. Monitor for unauthorized access

**If just forgotten:**

1. Generate a new key
2. Delete the old key after rotation

## API Key Limits

| Limit                    | Value                      |
| ------------------------ | -------------------------- |
| Keys per service account | 10                         |
| Key lifetime             | Unlimited (until rotation) |
| Key length               | 44 characters              |
| Rotation delay           | Immediate                  |
| Rate limiting            | 1000 req/min per key       |

## API Key Permissions

API keys have the same permissions as their associated service account:

```
ak-a1b2c3d4e5f6... → Service Account "ci-bot" → Developer role
```

The key inherits:

* Developer role permissions
* Resource restrictions
* Account access scope

## Next Steps

* [Create Service Accounts](/use/platform/service-accounts)
* [Manage Team Members](/use/platform/team-management)
* [Use the Admin API](/reference/introduction)