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

# API keys

> Create, list, revoke, and delete developer API keys for programmatic access

Use `api-keys` to create, list, revoke, and delete API keys for the authenticated user.

Supported actions: `all`, `list`, `create`, `revoke`, `delete`.

## Authentication model

<Warning>
  API key management endpoints require a session token (JWT). You cannot manage API keys using another API key.
</Warning>

***

## List API keys

Retrieves all API keys for the authenticated user. Both `all` and `list` return the same result.

<ParamField body="resource" type="string" required>
  Must be `"api-keys"`.
</ParamField>

<ParamField body="action" type="string" required>
  `"all"` or `"list"`.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="api_keys" type="object[]">
      <Expandable title="key properties">
        <ResponseField name="id" type="string" />

        <ResponseField name="name" type="string" />

        <ResponseField name="key_prefix" type="string">
          First 8 characters of the key (for display).
        </ResponseField>

        <ResponseField name="is_active" type="boolean" />

        <ResponseField name="last_used_at" type="string | null" />

        <ResponseField name="created_at" type="string" />

        <ResponseField name="revoked_at" type="string | null" />
      </Expandable>
    </ResponseField>

    <ResponseField name="count" type="number" />
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{
    api_keys: ApiKey[];
    count: number;
  }>({
    resource: "api-keys",
    action: "all",
  });
  ```

  ```bash cURL theme={null}
  curl -s https://api.helpgenie.ai/v1/api-keys \
    -H "Authorization: Bearer <session_token>"
  ```
</CodeGroup>

***

## Create API key

Creates a new API key. The full key is returned **once** in the response and cannot be retrieved again.

<ParamField body="resource" type="string" required>
  Must be `"api-keys"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"create"`.
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="name" type="string" required>
      Display name for the key (e.g. `"Production"`).
    </ParamField>
  </Expandable>
</ParamField>

### Response (status 201)

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="api_key" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="string" />

        <ResponseField name="name" type="string" />

        <ResponseField name="key_prefix" type="string" />

        <ResponseField name="key" type="string">
          The full API key. **Returned only at creation time.** Store it securely.
        </ResponseField>

        <ResponseField name="is_active" type="boolean" />

        <ResponseField name="last_used_at" type="string | null" />

        <ResponseField name="created_at" type="string" />

        <ResponseField name="revoked_at" type="string | null" />
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript Example request theme={null}
  const response = await ApiService.invoke<{ api_key: ApiKey }>(
    {
      resource: "api-keys",
      action: "create",
      data: { name: "Production" },
    },
    201
  );

  // Save response.api_key.key — it won't be shown again
  ```

  ```bash cURL theme={null}
  curl -s -X POST https://api.helpgenie.ai/v1/api-keys \
    -H "Authorization: Bearer <session_token>" \
    -H "Content-Type: application/json" \
    -d '{ "action": "create", "data": { "name": "Production" } }'
  ```
</CodeGroup>

***

## Revoke API key

Revokes a key immediately. Any subsequent requests using the revoked key will return `401`.

<ParamField body="resource" type="string" required>
  Must be `"api-keys"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"revoke"`.
</ParamField>

<ParamField body="id" type="string" required>
  The API key ID to revoke.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string">
      `"API key revoked successfully"`
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X PATCH https://api.helpgenie.ai/v1/api-keys/KEY_UUID \
    -H "Authorization: Bearer <session_token>"
  ```
</CodeGroup>

***

## Delete API key

Permanently deletes an API key record.

<ParamField body="resource" type="string" required>
  Must be `"api-keys"`.
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"delete"`.
</ParamField>

<ParamField body="id" type="string" required>
  The API key ID to delete.
</ParamField>

### Response

<ResponseField name="success" type="boolean" />

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean" />

    <ResponseField name="message" type="string">
      `"API key deleted permanently"`
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -s -X DELETE https://api.helpgenie.ai/v1/api-keys/KEY_UUID \
    -H "Authorization: Bearer <session_token>"
  ```
</CodeGroup>

***

## Using API keys

Once created, pass your API key on every request:

```
Authorization: Bearer hg_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
```

or:

```
X-API-Key: hg_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
```

API keys inherit the same permissions as the user who created them.

## Operational limits

* Maximum **5** active keys per user.
* Rate limit of **60 requests/minute** per key.

***

## Error responses

| Status | Code                  | Description                                                      |
| ------ | --------------------- | ---------------------------------------------------------------- |
| 400    | `VALIDATION_ERROR`    | Maximum 5 active API keys allowed. Revoke an existing key first. |
| 401    | `INVALID_TOKEN`       | Invalid or revoked API key                                       |
| 429    | `RATE_LIMIT_EXCEEDED` | Rate limit exceeded                                              |