# How to Connect to Campfire

To create a connection with Campfire, you create a dedicated API user in your own Campfire
instance, generate an API key for that user, and paste the key into Apideck Vault.

## Prerequisites

- An active Campfire account.
- Permission in Campfire to manage users and API keys (Settings > API Keys).

## How to Create Your API Key

Campfire mints API keys on a dedicated **API user** rather than on your own login, so the flow has
two parts: create the user, then create the key on that user.

1. Log in to your Campfire instance and open the API keys page at
   [https://app.meetcampfire.com/v2/settings/api-keys](https://app.meetcampfire.com/v2/settings/api-keys)
   (**Settings > API Keys** in the navigation menu).

2. Click **Create User** and fill in the **name**, **email** and **role** for the API user. Give the
   user a name you will recognise later, for example `Apideck Integration`, so the key is easy to
   trace in your audit log.

3. Choose the role that matches what your integration needs to do:

   | Role | Access |
   |------|--------|
   | `admin` | All APIs: full read and write access. |
   | `clerk` | Read all data, plus the ability to post draft entries. |
   | `view only` | GET requests only: read access, no writes. |

   Pick `admin` if you want Apideck to both read and write Campfire data (creating invoices, bills
   and other records). `clerk` and `view only` are valid choices for narrower, read-focused
   integrations: the connection still works, and Campfire refuses any write the role does not
   permit.

4. On the new user's record, click **Create API Key**.

5. **Copy the key immediately and store it somewhere safe.** Campfire shows the key only once: after
   you close the dialog it cannot be retrieved, and you would have to create a new key.

The vendor's own walkthrough of these steps is in the
[Campfire Quickstart](https://docs.campfire.ai/quickstart).

## Vault Connection Setup

Once you have your API key, configure the connection in Apideck Vault:

1. Paste the key into the **API Key** field.
2. Click **Save**.

   If the API key is valid, the connection is verified and you will see a success message.

3. If the integration will create bills, invoices or other financial records, re-open the connection
   settings and pick your **Entity** from the dropdown, then save again. The list is read live from
   your Campfire account and shows the entities (subsidiaries) the API user can see. Campfire needs
   to know which entity those records belong to.

### Connection settings

| Setting | Required | Notes |
|---------|----------|-------|
| **API Key** | Yes | The key generated for your Campfire API user. Handled as a sensitive value. |
| **Entity** | No | The Campfire entity (subsidiary) used for transactions. Needed when creating bills, invoices and other financial records. Selected from a list read from your Campfire account. |

Your Campfire account is now connected 🎉.

## Notes

- IP allowlisting is not required.
- Campfire documents no expiry for API keys, so the key is a static credential. Manage it in
  Campfire through the API user it belongs to, under **Settings > API Keys**.
- Access is bound to the role of the API user the key belongs to. To change what the integration can
  do, change that user's role in Campfire, or create a new API user with the role you want.

## Troubleshooting

- **The connection fails right after saving.** The key is almost certainly incomplete: it is shown
  only once, so a partial copy is the most common cause. Create a new API key on the same API user
  and paste it again.
- **Reads work but writes are rejected.** The API user's role does not allow writing. `view only`
  permits GET requests only and `clerk` allows posting draft entries only. Change the user's role to
  `admin` in Campfire, then save the connection again.
- **A created invoice or bill is rejected or lands on the wrong entity.** Check the **Entity**
  setting on the connection: Campfire needs the entity to be set for financial records, and it must
  be the entity those records belong to.
- **The Entity list is empty.** Save the connection with a valid API key first: the list is read
  from Campfire through that key. If it is still empty, confirm in Campfire that your account has
  entities configured and that the API user can read them.
- Still stuck? Contact [Apideck Support](https://help.apideck.com/en/articles/7774658).