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

# API keys

> Learn how API keys work on CodeQR.

API keys on CodeQR allow you to access your project programmatically. This is useful for integrating CodeQR into your application or with other tools and services.

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

API keys on CodeQR follow the format:

```bash .env theme={null}
CODEQR_API_KEY=codeqr_xxxxxxxx
```

By default, you can use this key to perform any API request without restriction, so it must be stored securely in your app's server-side code (such as in an environment variable or credential management system). Don’t expose this key on a website.

## Create an API key

You can create an API key by following these steps:

<Steps>
  <Step title="Go to your project">
    Go to **Settings** > [**API Keys**](https://app.codeqr.io/settings/tokens) in your project.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/codeqr/images/project-api-keys.png" alt="Project API keys on CodeQR" width="1468" height="249" />
    </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 your account or a [machine user](#machine-users).

    * **You**: This API key is tied to your user and can make requests against the selected project.
    * **Machine**: A machine user will be added to your project, and an API key associated with that machine user will be created.

    <Frame>
      <img src="https://mintcdn.com/codeqr/Dit-PkrrSHQLOViA/images/add-new-api-key.png?fit=max&auto=format&n=Dit-PkrrSHQLOViA&q=85&s=853c229517428c95a97b2a3edbf66e96" alt="Add new API key on CodeQR" width="1468" height="249" data-path="images/add-new-api-key.png" />
    </Frame>

    Click on the **Create API Key** button to create the key. Make sure to copy your API key and store it in a safe place. You won't be able to see it again.

    <Frame>
      <img src="https://mintcdn.com/codeqr/Dit-PkrrSHQLOViA/images/api-key-created.png?fit=max&auto=format&n=Dit-PkrrSHQLOViA&q=85&s=350990d0783755fd53405f4c54b07b7c" alt="API Key created on CodeQR" width="592" height="390" data-path="images/api-key-created.png" />
    </Frame>
  </Step>

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

    ```
    Authorization: Bearer codeqr_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 project.
</Tip>

## API key permissions

When creating a secret key, you can select the permissions it has, which will give the key access to certain (or all) resources on CodeQR. Here are the different permission options:

| Permission          | Description                                                                                                                                                                                                                                      |
| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **All permissions** | This API key will have full access to all resources.                                                                                                                                                                                             |
| **Read only**       | This API key will have read-only access to all resources.                                                                                                                                                                                        |
| **Restricted**      | This API key will have restricted access to some resources: <ul><li>[Links](/data-model#links)</li><li>[Analytics](/api-reference/endpoint/retrieve-analytics)</li><li>[Domains](/data-model#domains)</li><li>[Tags](/data-model#tags)</li></ul> |

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. When making API calls, if your API key has insufficient permissions, the error should tell you which permissions you need.

<Tip>
  You can only set permissions on Secret keys. Publishable keys only have access
  to certain endpoints, and cannot be restricted.
</Tip>

## Machine users

On CodeQR, 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 project, to avoid security risks in involving turnover or changes in project ownership.

<Warning>
  Machine users share the same permissions as the [owner
  role](https://codeqr.io/help/article/project-roles#owner-role) in a project.
  Make sure to only create machine users for trusted applications.
</Warning>

<Frame>
  <img src="https://mintcdn.com/codeqr/Dit-PkrrSHQLOViA/images/api-machine-users.png?fit=max&auto=format&n=Dit-PkrrSHQLOViA&q=85&s=7613291a4e07f5fa0caa8fda90da5e05" alt="Creating an API key associated with a machine user on CodeQR" width="1528" height="974" data-path="images/api-machine-users.png" />
</Frame>

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

<Frame>
  <img src="https://mintcdn.com/codeqr/Dit-PkrrSHQLOViA/images/machine-user.png?fit=max&auto=format&n=Dit-PkrrSHQLOViA&q=85&s=1b438c4549c82e71261cd6307b5c406c" alt="Machine user on CodeQR" 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>
