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

# API Keys

> Learn how to get your Heyoo API key.

API keys on Heyoo allow other apps to access your organisation programmatically. This is useful for integrating Heyoo with other tools and services.

Each API key is tied to a specific organisation – meaning you can use it to access that organisation's resources without having to worry about "leaking" access to other organisation.

<Tip>Heyoo API keys are prefixed with `hey_` for easy identification.</Tip>

## API key permissions

You can create 3 types of API keys on Heyoo:

1. **All permissions** – This API key will have full access to all resources.
2. **Read only** – This API key will have read-only access to all resources.
3. **Restricted** – This API key will have restricted access to some resources:
   * Campaigns
   * Analytics
   * Workspaces
   * Domains
   * Tags
   * API Keys

Depending on your use case, you might want to use one of these 3 options to limit the scope of the API key and improve security.

## Machine users

On Heyoo, you can create API keys that are associated with a "Machine user". This is particularly helpful when you don't want to associate the API key with a particular user in your workspace, to avoid security risks in involving turnover or changes in project ownership.

<Frame>
  <img src="https://mintcdn.com/heyoo/m-4b3E4nbPhIc4oV/images/api-machine-users.png?fit=max&auto=format&n=m-4b3E4nbPhIc4oV&q=85&s=644d1b1fbbadf71822b7600af8d3a3f9" alt="Creating an API key associated with a machine user on Heyoo" width="1528" height="974" data-path="images/api-machine-users.png" />
</Frame>

These machine users will show up on your workspace's **People** tab, but will not contribute to your workspace's user count.

<Frame>
  <img src="https://mintcdn.com/heyoo/m-4b3E4nbPhIc4oV/images/machine-user.png?fit=max&auto=format&n=m-4b3E4nbPhIc4oV&q=85&s=258dfaeb184e7e799d65ef979820b17a" alt="Machine user on Heyoo" width="1468" height="249" data-path="images/machine-user.png" />
</Frame>

<Tip>
  If you delete an API key associated with a machine user, the machine user will
  be deleted. Vice versa, if you delete a machine user, their corresponding API
  key will be deleted as well.
</Tip>

<Warning>
  Machine users are available exclusively to workspace owners. If you are not
  the owner of the workspace, this option will be disabled when creating an API
  key.
</Warning>

## How to create an API key

You can create an API key by following these steps:

<Steps>
  <Step title="Go to your workspace">
    Go to **Settings** > **API Keys** in your workspace.

    <Frame>
      <img src="https://mintcdn.com/heyoo/m-4b3E4nbPhIc4oV/images/workspace-api-keys.png?fit=max&auto=format&n=m-4b3E4nbPhIc4oV&q=85&s=e114e6b5b153067069d8048fb463c053" alt="Workspace API keys on Heyoo" width="1468" height="249" data-path="images/workspace-api-keys.png" />
    </Frame>
  </Step>

  <Step title="Create an API Key">
    Click on the "Create" button and select permissions you want to grant to
    the API key.

    Select between "You" and "Machine" to associate the API key with a user or a [machine user](#machine-users).

    * **You** – This API key is tied to your user and can make requests against the selected workspace.
    * **Machine** – A machine user will be added to your workspace, and an API key will be created.

    <Frame>
      <img src="https://mintcdn.com/heyoo/m-4b3E4nbPhIc4oV/images/add-new-api-key.png?fit=max&auto=format&n=m-4b3E4nbPhIc4oV&q=85&s=5bb25ffaed269c3bd761fea6b5905ad1" alt="Add new API key on Heyoo" width="1468" height="249" data-path="images/add-new-api-key.png" />
    </Frame>

    When making API calls, if your API Key have insufficient permissions, the error should tell you which permissions you need.

    Make sure to copy your API key and store it in a safe place. You won't be able to see it again.
  </Step>

  <Step title="Use your API Key">
    Now that you have your API key, you can use it to access your workspace's resources programmatically via SDKs or within any API request as a bearer token.

    ```
    Authorization: Bearer hey_xxxx
    ```
  </Step>
</Steps>

<Tip>
  We recommend creating API keys with the least privilege necessary to perform
  the required tasks. This helps to reduce the risk of unauthorized access to
  your workspace.
</Tip>