> For the complete documentation index, see [llms.txt](https://docs.carbon.inc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carbon.inc/developers/http-api/enabling-api-access.md).

# Enabling API access

How to enable a Carbon subaccount for API trading and grant an API key permissions, in the Carbon app or over the API, and how to verify or revoke access.

Before an API key can trade a subaccount, that subaccount must be **enabled for API access** and the key must be **granted permissions**. A subaccount needs three approvals in place:

| Approval                 | What it authorizes                                                                   |
| ------------------------ | ------------------------------------------------------------------------------------ |
| **API Access**           | The subaccount is opted in to programmatic (API) trading.                            |
| **On-Chain Permissions** | On-chain approval allowing API-driven actions on the subaccount.                     |
| **Solver Permission**    | The solver is authorized to execute on your behalf (required for instant execution). |

There are two ways to set this up.

### Method 1 — Frontend (recommended)

Do it once in the Carbon app: [**app.carbon.inc/account/api-management**](https://app.carbon.inc/account/api-management)

1. **Select the account** (crypto or tradfi subaccount) from the dropdown at the top of the page.
2. Under **Account Permissions**, click **Enable**. This walks you through approving all three: **API Access**, **On-Chain Permissions**, and **Solver Permission**. If any later shows as not enabled, use **Revalidate**.
3. Click **Create API** to mint an API key, then set its permissions.
4. **Copy the key secret** — it's shown only once. Store it securely.

Your keys appear under **Your APIs** with their status; use **Manage** to adjust permissions or revoke a key.

> This is the recommended path because the app handles the wallet signatures and on-chain approvals for you. Once a subaccount is enabled here, your API keys can trade it without any further wallet interaction.

### Method 2 — Programmatic (API)

You can perform the gateway-side setup over the API with a **session JWT** (see [Authentication](https://docs.carbon.inc/developers/http-api/authentication.md)):

```http
# 1. Create an API key
POST /v1/api-keys/create

# 2. Enable API access on the subaccount
POST /v1/account-auth/subaccount/toggle-access
{ "subaccountAddress": "0x…", "chainId": 42161, "enable": true }

# 3. Delegate permissions to the key
POST /v1/account-auth/delegate-access
{ "subaccountAddress": "0x…", "apiKeyIdentifier": "…",
  "permissions": ["OPEN_POSITION", "CLOSE_POSITION"] }

# 4. (For instant execution) register a solver instant-action token
POST /v1/account-auth/instant-action/token
```

Permissions (`AllowedPermission`): `ALL`, `OPEN_POSITION`, `CLOSE_POSITION`, `CANCEL_POSITION`, `VIEW_DETAILS`.

> The **On-Chain** and **Solver** approvals require signatures from the owning wallet. Most integrators complete the enabling step once in the frontend and then use API keys for everything else — even when scripting the rest.

#### Verify and revoke

| Action                          | Endpoint                                                                    |
| ------------------------------- | --------------------------------------------------------------------------- |
| Check a subaccount's access     | `GET /v1/account-auth/verify?subaccountAddress=0x…`                         |
| List a subaccount's delegations | `GET /v1/account-auth/subaccount/list-api-delegations`                      |
| Revoke a delegation             | `DELETE /v1/account-auth/delegation/{subaccountAddress}/{apiKeyIdentifier}` |

A key that attempts an action it wasn't granted is rejected with `403`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.carbon.inc/developers/http-api/enabling-api-access.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
