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

# Authentication

> Learn how to authenticate with the Bizzy API

The Bizzy API uses API keys to authenticate requests. You can create and manage
API keys from your organization settings in the dashboard.

## Creating an API Key

1. Sign in to the [Bizzy Dashboard](https://www.bizzyco.ai/home)
2. Navigate to **Settings** > **API Keys**
3. Click **Create API Key**
4. Give your key a descriptive name (e.g., "Production Server" or "Development")
5. Select the permission scopes your key needs
6. Click **Create** and copy your key immediately

<Warning>
  Your API key is only shown once when created. Store it securely - you won't
  be able to see it again. If you lose your key, you'll need to create a new
  one.
</Warning>

## Using Your API Key

Include your API key in the `Authorization` header of every request using the
Bearer token format:

```
Authorization: Bearer your-api-key
```

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.bizzyco.ai/v1/contacts \
    -H "Authorization: Bearer sk_live_abc123..."
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://api.bizzyco.ai/v1/contacts', {
      headers: {
          Authorization: 'Bearer sk_live_abc123...',
      },
  });

  const { data } = await response.json();
  ```

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

  response = requests.get(
      'https://api.bizzyco.ai/v1/contacts',
      headers={
          'Authorization': 'Bearer sk_live_abc123...',
      }
  )

  data = response.json()['data']
  ```
</CodeGroup>

## Permission Scopes

API keys are scoped to specific permissions that control what resources they can
access. When creating a key, grant only the permissions your integration needs.

### Available Scopes

| Resource       | Actions             | Description                              |
| -------------- | ------------------- | ---------------------------------------- |
| `contacts`     | read, write, delete | Manage contacts and their details        |
| `customers`    | read, write, delete | Manage customer records                  |
| `businesses`   | read, write, delete | Manage business profiles                 |
| `messages`     | read, write, delete | Access email, SMS, and voice messages    |
| `automations`  | read, write, delete | Configure automation workflows           |
| `domains`      | read, write, delete | Manage custom domains                    |
| `users`        | read, write, delete | Manage user profiles and settings        |
| `organization` | read, write, delete | Manage organization settings and members |
| `api_keys`     | read, write, delete | Manage API keys and their permissions    |
| `resources`    | read, write, delete | Access shared resources and analytics    |

### Permission Inheritance

Permissions follow a hierarchical model. Granting access to a parent resource
also grants access to its child resources:

* `contacts` includes `contacts.emails`, `contacts.phones`,
  `contacts.addresses`, `contacts.tags`, `contacts.notes`
* `customers` includes `customers.contacts`
* `businesses` includes `businesses.details`, `businesses.tags`,
  `businesses.contacts`, `businesses.addresses`
* `messages` includes `messages.email`, `messages.sms`, `messages.voice`
* `automations` includes `automations.actions`
* `domains` includes `domains.dns`, `domains.verification`
* `users` includes `users.profile`, `users.settings`
* `organization` includes `organization.settings`, `organization.billing`
* `resources` includes `resources.analytics`

### HTTP Methods and Permissions

| HTTP Method | Required Permission |
| ----------- | ------------------- |
| GET         | `read`              |
| POST        | `write`             |
| PUT, PATCH  | `write`             |
| DELETE      | `delete`            |

## Authentication Errors

If authentication fails, you'll receive a `401 Unauthorized` response:

```json theme={null}
{
    "error": {
        "code": "UNAUTHORIZED",
        "message": "Invalid or missing API key"
    }
}
```

Common causes:

* Missing `Authorization` header
* Invalid or revoked API key
* Malformed Bearer token (missing "Bearer " prefix)

If your key lacks permission for a specific action, you'll receive a
`403 Forbidden` response:

```json theme={null}
{
    "error": {
        "code": "INSUFFICIENT_PERMISSIONS",
        "message": "Missing write permission for contacts",
        "details": {
            "required": {
                "resource": "contacts",
                "action": "write"
            },
            "hint": "Contact your administrator to request additional permissions"
        }
    }
}
```

## Security Best Practices

<AccordionGroup>
  <Accordion title="Never commit API keys to version control">
    Use environment variables or a secrets manager to store your API keys. Add `.env` files to your `.gitignore`.

    ```bash theme={null}
    # .env (never commit this file)
    BIZZY_API_KEY=sk_live_abc123...
    ```

    ```typescript theme={null}
    // Use environment variables
    const apiKey = process.env.BIZZY_API_KEY;
    ```
  </Accordion>

  <Accordion title="Use separate keys for each environment">
    Create different API keys for development, staging, and production. This
    limits the blast radius if a key is compromised.
  </Accordion>

  <Accordion title="Grant minimum required permissions">
    Follow the principle of least privilege. Only grant the specific permissions
    your integration needs. A read-only dashboard doesn't need write access.
  </Accordion>

  <Accordion title="Rotate keys regularly">
    Periodically create new API keys and deprecate old ones. This limits the
    window of exposure if a key is leaked.
  </Accordion>

  <Accordion title="Monitor API key usage">
    Review your API key activity in the dashboard regularly. Revoke any keys showing suspicious activity immediately.
  </Accordion>
</AccordionGroup>

## Server-Side Only

<Warning>
  API keys should only be used in server-side code. Never expose your API key
  in client-side JavaScript, mobile apps, or any code that runs in the
  browser.
</Warning>

If you need to access the Bizzy API from a client application, implement a
backend proxy that handles authentication on behalf of your users.