> For the complete documentation index, see [llms.txt](https://docs.ipaware.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipaware.io/dashboard/markdown.md).

# API Keys

### Overview

Each API key consists of:

* **Key ID:** Public identifier (e.g., `key_abc123...`) - safe to log
* **Secret Key:** Private credential - shown only once during creation
* **Name:** Descriptive label for identification
* **Role:** Determines permissions and access levels
* **Status:** Active or revoked

***

### Creating an API Key

**Steps:**

1. **Open Creation Modal**
   * Navigate to the **API Keys** tab
   * Click **+ Create New Key**
2. **Configure Key**
   * **Key Name:** Enter a descriptive name (e.g., "Production Server", "Mobile App")
   * **Role:** Select the appropriate role from the dropdown
     * Choose based on the principle of least privilege
3. **Create Key**
   * Click **Create**
   * The system generates your key immediately
4. **Save Secret Key**
   * **IMPORTANT:** The secret key is shown only once
   * Copy the secret key immediately
   * Store it securely (password manager, environment variables, secrets manager)
   * The Key ID is also displayed for reference
5. **Confirm**
   * Click **I have copied it** to close the modal
   * Your new key appears in the API Keys table

> **Security Warning:** Never commit secret keys to version control or share them publicly!

***

### Managing API Keys

#### Viewing API Keys

The API Keys table displays:

| Column      | Description                            |
| ----------- | -------------------------------------- |
| **Name**    | Your descriptive label                 |
| **Key ID**  | Public identifier (starts with `key_`) |
| **Role**    | Assigned permission role               |
| **Created** | Date the key was created               |
| **Status**  | Active (green badge)                   |
| **Actions** | Edit and Revoke buttons                |

#### Editing an API Key

You can update the name and role of existing keys: 

**Steps:**

1. Click **Edit** next to the key you want to modify
2. Update the **Key Name** (optional)
3. Change the **Role** (optional)
4. Click **Save Changes**

> **Note:** You cannot change the Key ID or retrieve the secret key after creation.

#### Revoking an API Key

Permanently disable a key to prevent further API access: 

**Steps:**

1. Click **Revoke** next to the key
2. Read the warning: "Applications using this key will stop working"
3. Click **Revoke Key** to confirm **Effects:**

* Key is immediately deactivated
* All API requests using this key will fail
* Key is removed from the table
* Action cannot be undone

> **Use Case:** Revoke keys when rotating credentials, removing integrations, or if a key is compromised.

***

### API Key Roles

Roles determine what actions an API key can perform.

#### Custom Roles

### Organizations can create custom roles with specific permissions. See [Roles & Permissions](/dashboard/interactive-blocks.md) for details.

### Using API Keys

#### Authentication

Include your API key in requests using the `Authorization` header.

#### Best Practices

**Security:**

* Store keys in environment variables, not in code
* Use different keys for different environments (dev, staging, production)
* Rotate keys regularly (every 90 days recommended)
* Revoke unused keys immediately
* Never log or display secret keys 

**Organization:**

* Use descriptive names (include environment and purpose)
* Document which key is used where
* Assign minimal necessary permissions
* Review keys quarterly 

**Monitoring:**

* Track which keys are actively used
* Monitor for unusual activity
* Set up alerts for failed authentication attempts

***

### Key Rotation

Regularly rotating API keys improves security: 

**Rotation Process:**

1. **Create new key**
   * Generate a new API key with the same role
   * Name it clearly (e.g., "Production Server v2")
2. **Update applications**
   * Deploy the new key to your applications
   * Test thoroughly before proceeding
3. **Monitor transition**
   * Ensure all services are using the new key
   * Check for any authentication errors
4. **Revoke old key**

   * Once confirmed, revoke the old key
   * Document the rotation in your change log 

   **Recommended Schedule:**

* Production keys: Every 90 days
* Development keys: Every 180 days
* Compromised keys: Immediately

***

### Troubleshooting

#### "Invalid API Key" Error

**Possible causes:**

* Key was revoked
* Incorrect secret key (typo or truncation)
* Key doesn't have required permissions
* IP not whitelisted (if whitelist is enabled) 

**Solutions:**

1. Verify the secret key is correct and complete
2. Check if key appears in the API Keys table
3. Confirm the key's role has necessary permissions
4. Ensure your IP is whitelisted

#### Key Not Working After Creation

**Check:**

* Secret key was copied correctly (no extra spaces)
* Using the secret key, not the Key ID
* Authorization header is formatted correctly
* API endpoint URL is correct

#### Can't Create More Keys

**Reason:** Some plans have limits on the number of active API keys 

**Solutions:**

* Revoke unused keys
* Upgrade your plan for higher limits
* Consolidate applications to use fewer keys

***

### Security Considerations

#### Key Compromise

If you suspect a key has been compromised:

1. **Revoke immediately** - Don't wait
2. **Create replacement** - Generate a new key
3. **Update applications** - Deploy the new key
4. **Investigate** - Determine how the compromise occurred
5. **Review logs** - Check for unauthorized access
6. **Notify team** - Inform relevant stakeholders

#### Storage Recommendations

**Good Practices:**

* Environment variables
* Secrets management services (AWS Secrets Manager, HashiCorp Vault)
* Encrypted configuration files
* Password managers (for manual testing) 

**Bad Practices:**

* ❌ Hardcoded in source code
* ❌ Committed to Git repositories
* ❌ Stored in plain text files
* ❌ Shared via email or chat
* ❌ Logged in application logs

***

### Permissions Required

To manage API keys, you need these permissions:

* **Create keys:** `api.key.create`
* **Edit keys:** `api.key.update`
* **Revoke keys:** `api.key.delete`
* **View keys:** `api.key.view` 

***

### Next Steps

* Assign roles to keys for granular permissions
* Set up IP whitelist for additional security
* Monitor usage to track API consumption
* Invite team members to collaborate on API management


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ipaware.io/dashboard/markdown.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.