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

# API Key Management

> Create and manage API keys for programmatic access to Bizzy

API keys allow external applications and scripts to access your Bizzy
organization programmatically. This guide covers creating, configuring, and
securing your API keys.

<Note>
  This guide covers API keys for REST API access. AI agents (Claude, Cursor,
  Windsurf, etc.) connect through the [MCP server](/mcp-server/introduction),
  which uses its own authentication flow rather than API keys.
</Note>

## Prerequisites

* You must be an **Owner** to manage API keys
* Admins and Users cannot create, view, or revoke API keys

## Creating an API Key

To create a new API key:

1. Navigate to **Settings > Security > API Keys**
2. Click **Create API Key**
3. Enter a descriptive name (e.g., "Production CRM Integration")
4. Configure permissions (see below)
5. Optionally set an expiration date
6. Click **Create**

<Note>
  The full API key is displayed only once after creation. Copy it immediately
  and store it securely. You cannot retrieve the full key later.
</Note>

### API Key Format

Bizzy API keys are prefixed with `sk_` followed by a long random secret:

```
sk_a1b2c3...
```

* `sk_` - Indicates a secret key
* Followed by a unique random string

For security, Bizzy stores only a hash of each key — never the key itself. After
creation, the full key is shown once; the dashboard thereafter displays a masked
preview (the `sk_` prefix plus the last four characters, e.g. `sk_a1b…c3d4`) so
you can identify a key without exposing it.

## Setting Permissions

API keys support fine-grained permissions that control which resources the key
can access and what actions it can perform.

### Permission Structure

Each permission specifies:

| Component | Description                 | Example                   |
| --------- | --------------------------- | ------------------------- |
| Resource  | What the key can access     | `contacts`, `messages`    |
| Action    | What operations are allowed | `read`, `write`, `delete` |

### Common Permission Patterns

**Read-Only Access**

```json theme={null}
{
    "contacts": { "read": true, "write": false, "delete": false },
    "customers": { "read": true, "write": false, "delete": false }
}
```

**Full Contact Management**

```json theme={null}
{
    "contacts": { "read": true, "write": true, "delete": true }
}
```

**Messaging Only**

```json theme={null}
{
    "messages": { "read": true, "write": true, "delete": false }
}
```

### Permission Inheritance

Permissions cascade to child resources. Granting access to `contacts`
automatically includes:

* `contacts.emails`
* `contacts.phones`
* `contacts.addresses`
* `contacts.tags`
* `contacts.notes`

You can override child permissions to restrict access further.

## Key Expiration

Set an expiration date to automatically disable API keys after a certain period:

| Use Case                | Recommended Expiration          |
| ----------------------- | ------------------------------- |
| Temporary integrations  | 7-30 days                       |
| Contractor access       | Project duration                |
| Production integrations | 90-365 days                     |
| Internal tools          | No expiration (rotate manually) |

<Note>
  Expired keys return a `401 Unauthorized` error. Create a new key before the
  old one expires to avoid service interruption.
</Note>

## Monitoring Key Usage

Track API key activity from the API Keys dashboard:

| Metric    | Description                                      |
| --------- | ------------------------------------------------ |
| Key       | Masked preview (`sk_…last4`) to identify the key |
| Last Used | Timestamp of the most recent API call            |
| Created   | When the key was created                         |
| Expires   | Expiration date (if set)                         |
| Status    | Active, Expired, or Revoked                      |

Use the "Last Used" timestamp to identify unused keys that should be revoked.

## Revoking Keys

To revoke an API key:

1. Navigate to **Settings > Security > API Keys**
2. Find the key to revoke
3. Click **Revoke**
4. Confirm the action

<Note>
  Revoked keys cannot be restored. Any application using the revoked key will
  immediately lose access.
</Note>

### When to Revoke

Revoke API keys immediately when:

* A key may have been compromised
* An employee with key access leaves the organization
* An integration is decommissioned
* A key hasn't been used in 90+ days

## Security Best Practices

### Key Storage

* **Never** commit API keys to version control
* Use environment variables or secret management services
* Restrict file permissions on configuration files containing keys

<CodeGroup>
  ```bash Environment Variable theme={null}
  export BIZZY_API_KEY="sk_live_abc123..."
  ```

  ```typescript TypeScript theme={null}
  const apiKey = process.env.BIZZY_API_KEY;
  ```

  ```python Python theme={null}
  import os
  api_key = os.environ.get('BIZZY_API_KEY')
  ```
</CodeGroup>

### Key Rotation

Regularly rotate API keys to limit exposure from potential leaks:

1. Create a new key with the same permissions
2. Update your application to use the new key
3. Verify the new key works in production
4. Revoke the old key

Recommended rotation schedule:

| Environment     | Rotation Frequency |
| --------------- | ------------------ |
| Production      | Every 90 days      |
| Development     | Every 30 days      |
| After incidents | Immediately        |

### Principle of Least Privilege

Grant only the permissions each integration needs:

* Read-only keys for reporting and analytics
* Resource-specific keys for focused integrations
* Separate keys for separate applications

### Audit Regularly

Review your API keys monthly:

* Remove unused keys (no activity in 90+ days)
* Verify permissions match current requirements
* Check expiration dates and rotate as needed

## Troubleshooting

### Common Errors

| Error                   | Cause                    | Solution                                |
| ----------------------- | ------------------------ | --------------------------------------- |
| `401 Unauthorized`      | Invalid or expired key   | Check key value and expiration          |
| `403 Forbidden`         | Insufficient permissions | Verify key has required resource/action |
| `429 Too Many Requests` | Rate limit exceeded      | Implement backoff and retry logic       |

### Debugging Permission Issues

If your API key returns `403 Forbidden`:

1. Check the error response for the required permission
2. Compare against your key's configured permissions
3. Update the key or create a new one with correct permissions

## Next Steps

<CardGroup cols={2}>
  <Card title="API Introduction" icon="code" href="/api-reference/introduction">
    Learn how to use the Bizzy API
  </Card>

  <Card title="Authentication" icon="lock" href="/api-reference/authentication">
    Understand API authentication methods
  </Card>
</CardGroup>