# How to Connect to Folk

This guide walks you through creating an API key in Folk and pasting it into Vault to connect your workspace.

- [Before you start](#before-you-start)
- [How to create your API key](#how-to-create-your-api-key)
- [Vault connection setup](#vault-connection-setup)
- [Authentication method](#authentication-method)
- [Permissions and key ownership](#permissions-and-key-ownership)
- [Revoking an API key](#revoking-an-api-key)
- [Troubleshooting](#troubleshooting)

## Before you start

- Your workspace needs to be on Folk's Premium plan. The API is a Premium feature, so a workspace on Standard cannot create a key that works.
- You do not need an admin role. Any member of the workspace can create an API key.
- Decide who creates the key before you create it. The key belongs to that person, and that has consequences described under [Permissions and key ownership](#permissions-and-key-ownership).

## How to create your API key

1. Log in to Folk.

2. Open **Settings** in your Folk workspace, then go to the **API** section. Folk documents this path in its help centre article [folk API](https://help.folk.app/en/articles/11666479-folk-api).

3. Click **New API key**. Folk names this button in its [quick start guide](https://developer.folk.app/guides/quick-start).

4. Give the key a name that will help you recognise it later, for example "Apideck Integration".

5. Copy the key and store it somewhere secure. Folk's own guidance is to treat it as a secret: anyone holding it has programmatic access to your workspace data.

## Vault connection setup

Enter your API key in Vault:

- **API Key**: the key you created in Folk.

Click **Save** to complete the connection.

You are connected.

## Authentication method

Folk uses bearer token authentication. When you connect through Vault, your API key is included in the `Authorization` header on every request:

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

## Permissions and key ownership

An API key belongs to the member who created it.

Because the key is tied to its creator, Folk states that when a member is removed from a workspace, the integrations that member set up stop working, and Folk documents no way to hand a key over to somebody else. Two things follow:

- Create the key from the account of someone who is expected to stay with the workspace, rather than from a temporary or contractor account.
- If that person does leave, the connection stops working. Restore it by having someone still in the workspace create a new key and paste it into Vault, following the steps above.

## Revoking an API key

To revoke a key:

1. Open **Settings** in your Folk workspace, then the **API** section.
2. Find the key you want to revoke.
3. Delete it and confirm.

Deleting a key cannot be undone. If the key you deleted was the one in use, create a new key and update the Vault connection with it.

## Troubleshooting

**Requests fail with an authentication error.** The key has most likely been deleted in Folk, or was pasted incompletely. Create a new key and update the Vault connection.

**The connection stops working without anyone changing it.** Two causes are worth checking. The member who created the key may have been removed from the workspace, in which case the key stops working with their membership and a new key is needed. The workspace may also have dropped off the Premium plan, which is what carries API access.

**The connection does not report as healthy.** Apideck checks the health of a Folk connection by listing the workspace's users. If the check fails, confirm that the member who created the key is still a member of the workspace, and create and paste a new key if they are not.

If something is still not working, contact [Apideck Support](https://help.apideck.com/en/articles/7774658).