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

# Authenticate Your Requests to the Zolt REST API Safely

> Generate a Zolt API key, attach it to your requests using the Authorization header, and manage scopes and revocation for secure integrations.

Zolt uses API key-based authentication to verify the identity of every integration that calls the API. Each request you make must include a valid API key in the `Authorization` header — requests without a key, or with an invalid key, are rejected before they reach any endpoint. API keys are tied to a specific Zolt workspace and inherit the permissions defined by their assigned scope.

## Generating an API Key

You create API keys directly inside Zolt's settings. Each key should correspond to a single integration or use case so you can revoke access independently without affecting other systems.

<Steps>
  <Step title="Open API Keys settings">
    In Zolt, click your workspace avatar in the bottom-left corner, then navigate to **Settings** → **Developer** → **API Keys**.
  </Step>

  <Step title="Generate a new key">
    Click **Generate New Key** in the top-right corner of the API Keys page.
  </Step>

  <Step title="Name your key">
    Enter a descriptive name that identifies the integration this key is for — for example, `GitHub Sync` or `Analytics Export`. Select the appropriate scope for the key (see [API Key Scopes](#api-key-scopes) below), then click **Create**.
  </Step>

  <Step title="Copy and store the key">
    Your new API key is displayed once. Copy it immediately and store it in a secure location such as a password manager or secrets manager. You will not be able to retrieve the key value again after closing this dialog.
  </Step>
</Steps>

<Warning>
  Zolt only displays your API key **once**, at the moment of creation. If you navigate away or close the dialog before copying it, you will need to revoke the key and generate a new one. Never commit API keys to source control or expose them in client-side code.
</Warning>

## Making Authenticated Requests

Pass your API key in the `Authorization` header of every request using the `Bearer` scheme:

```http title="Authorization Header" theme={null}
Authorization: Bearer YOUR_API_KEY
```

The following examples show a complete authenticated request to list all projects in your workspace:

<CodeGroup>
  ```bash title="cURL" theme={null}
  curl --request GET \
    --url https://api.zolt.io/v1/projects \
    --header "Authorization: Bearer YOUR_API_KEY" \
    --header "Content-Type: application/json"
  ```

  ```javascript title="JavaScript (fetch)" theme={null}
  const response = await fetch("https://api.zolt.io/v1/projects", {
    method: "GET",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python title="Python (requests)" theme={null}
  import requests

  url = "https://api.zolt.io/v1/projects"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
  }

  response = requests.get(url, headers=headers)
  data = response.json()
  print(data)
  ```
</CodeGroup>

## API Key Scopes

When generating a key, you assign it a scope that controls what the key is permitted to do. Follow the principle of least privilege — grant only the scope your integration actually needs.

| Scope   | Permissions                                                                                                                                          |
| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read`  | Retrieve any resource in the workspace (projects, tasks, members, webhooks). Cannot create, update, or delete anything.                              |
| `write` | All `read` permissions, plus the ability to create, update, and delete projects, tasks, and other non-administrative resources.                      |
| `admin` | All `write` permissions, plus the ability to manage team members, billing settings, workspace configuration, and API keys themselves. Use sparingly. |

## Revoking an API Key

If a key is compromised, no longer needed, or belongs to a decommissioned integration, revoke it immediately to prevent unauthorized access.

<Steps>
  <Step title="Open API Keys settings">
    Navigate to **Settings** → **Developer** → **API Keys** in your Zolt workspace.
  </Step>

  <Step title="Find the key to revoke">
    Locate the key by its name in the list. You can also see the last time each key was used, which helps identify dormant keys.
  </Step>

  <Step title="Delete the key">
    Click the **⋯** menu next to the key and select **Revoke Key**. Confirm the action in the dialog that appears. The key is invalidated immediately — any subsequent requests using it will receive a `401 Unauthorized` response.
  </Step>
</Steps>

## Authentication Errors

If your request is rejected due to an authentication or authorization problem, the API returns one of the following error responses:

| Status | Code           | Meaning                                                                                                                                                                                         |
| ------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | `unauthorized` | The `Authorization` header is missing, malformed, or contains an invalid or revoked API key.                                                                                                    |
| `403`  | `forbidden`    | The API key is valid, but it does not have the scope required to perform the requested action. Regenerate the key with a broader scope or use a key that already has the necessary permissions. |

For the full error response format and a complete list of error codes, see the [Errors](/developers/errors) reference.