> 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

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](/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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.