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

# API Keys

> Create and securely use account-scoped API keys with granular permissions.

API keys authenticate private account and trading requests. Each key has a public key and a secret key, an account scope, and a set of permissions.

## Create an API key

1. Sign in at [qfex.com](https://qfex.com) and select your profile in the bottom right corner.

   ![](https://mintcdn.com/qfex/LD0EtLtcrjzAI_0J/images/api_key/1.png?fit=max\&auto=format\&n=LD0EtLtcrjzAI_0J\&q=85\&s=33b5ace9fa054bfb6270adb08a37a0e1)

2. Navigate to **Developer Settings** via the carousel.

   ![](https://mintcdn.com/qfex/LD0EtLtcrjzAI_0J/images/api_key/2.png?fit=max\&auto=format\&n=LD0EtLtcrjzAI_0J\&q=85\&s=8d6618d0c17a0bf5b5dd78f1985b660f)

3. Click **Generate public and secret API Keys**.

   ![](https://mintcdn.com/qfex/LD0EtLtcrjzAI_0J/images/api_key/3.png?fit=max\&auto=format\&n=LD0EtLtcrjzAI_0J\&q=85\&s=1b7b5ab90e72d02f9bcfa133c03695db)

4. Ensure you have 2FA enabled.

   ![](https://mintcdn.com/qfex/LD0EtLtcrjzAI_0J/images/api_key/4.png?fit=max\&auto=format\&n=LD0EtLtcrjzAI_0J\&q=85\&s=a8f712aee7ef85e4d78fd1abcbf14246)

5. Provide a descriptive name, choose the account access and permissions the key needs, and confirm.

   ![](https://mintcdn.com/qfex/LD0EtLtcrjzAI_0J/images/api_key/5.png?fit=max\&auto=format\&n=LD0EtLtcrjzAI_0J\&q=85\&s=be500c5f1c214ca058bc919521272a23)

6. **Copy** the generated key and store it securely—it will only be shown once.

   ![](https://mintcdn.com/qfex/LD0EtLtcrjzAI_0J/images/api_key/6.png?fit=max\&auto=format\&n=LD0EtLtcrjzAI_0J\&q=85\&s=cca987090f4920ab4953b408c9d2392f)

## Account access and permissions

Each API key is limited by both its **account access** and its **permissions**. A request must satisfy both settings.

For account access, choose either:

* **A specific account**: The key can be used only with the selected primary account or subaccount.
* **All accounts**: The key can be used with any account you own. Use this only when the integration genuinely needs access across accounts.

Permissions control what the key can do:

| Permission | Allows |
| - | - |
| Execute orders | Place, modify, and cancel orders, and perform related trading actions. |
| View orders | Read orders, fills, and trading history. |
| View positions | Read open position information. |
| View balance (`view_balance`) | Read balances, equity, fees, deposit addresses with `GET /address`, and registered withdrawal addresses with `GET /withdrawal-addresses`. |
| Deposit and withdraw (`deposit_withdraw`) | Use supported funding and withdrawal actions, rotate deposit addresses, and manage bank accounts. Crypto withdrawals require a registered destination. Available only to keys with All accounts access. |

Create keys with only the permissions required for their intended use. For example, reporting software may need view permissions but should not need order execution or withdrawal access.

## Use an API key with a third party

If you authorize a trusted third-party application to access QFEX with an API key:

1. Create a dedicated key for that application. Do not reuse your personal integration key.
2. Limit it to the required account and enable only the permissions the application needs.
3. Provide the public and secret key through a secure channel. The application never needs your QFEX password or MFA codes.
4. The application must keep the secret key on a secure server and use it to sign authenticated requests. It must never expose the secret in browser code, mobile applications, logs, URLs, or source control.
5. Revoke the key from Developer Settings when the integration is no longer needed or if either credential may have been exposed.

The secret key is displayed only once. QFEX cannot display it again after creation; create a replacement key if it is lost.

For direct integrations, see [WebSocket authentication](https://docs.qfex.com/websocket/channels/trade/authenticate.md) for the trading signing flow or [Programmatic deposits and withdrawals](https://docs.qfex.com/api-reference/programmatic-funding.md) for funding REST requests. A third-party application can also use [QFEX OAuth](https://docs.qfex.com/api-reference/builder-integration.md) or [wallet-signed builder registration](https://docs.qfex.com/api-reference/builder-wallet-registration.md) to connect a user account.

> [!WARNING]
>
> Treat the secret key like a password. Anyone who has both key values can act within the account access and permissions you selected.

## Builder-issued API keys

[Builder wallet registration](https://docs.qfex.com/api-reference/builder-wallet-registration.md) lets an enabled builder create a user's trading key after the user signs a wallet message. The builder authenticates the registration request with its own API key and `register_user` permission.

The returned user key is restricted to the main account and grants trading, account reads, deposit-address reads, and crypto withdrawals to registered destinations. Its `view_balance` permission authorizes `GET /address` and `GET /withdrawal-addresses`. Registered-destination crypto withdrawals with `POST /withdraw` are enabled through builder key issuance and replacement; this access is not selectable in Developer Settings. It has `deposit_withdraw` disabled, so it cannot rotate deposit addresses, manage bank accounts, or withdraw USD. See [programmatic funding](https://docs.qfex.com/api-reference/programmatic-funding.md) for the requests.

The key is labelled `builder-` followed by the builder's username. Creating another key for the same user and builder label replaces the previous key. Keys with labels starting with `builder-` or `managed` are excluded from the normal API-key listing.

## Create an API key programmatically

Standard programmatic key creation uses a QFEX user session, not an existing API key. First [authenticate with a wallet](https://docs.qfex.com/api-reference/wallet-authentication.md) or another supported sign-in method, then complete MFA to obtain a recently elevated access token.

Send the elevated token to the key-generation endpoint. Supply every permission explicitly so the key cannot gain permissions through a default-value change:

```javascript theme={null}
const QFEX_AUTH_URL = "https://verify.qfex.com";
const QFEX_AUTH_CLIENT_KEY = "YOUR_QFEX_AUTH_CLIENT_KEY";

export async function createQfexApiKey({
  accessToken,
  name,
  accountId = "*",
  permissions = {},
}) {
  const response = await fetch(
    `${QFEX_AUTH_URL}/rest/v1/rpc/generate_api_key_v3`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        apikey: QFEX_AUTH_CLIENT_KEY,
        Authorization: `Bearer ${accessToken}`,
      },
      body: JSON.stringify({
        p_name: name,
        p_account_id: accountId,
        p_execute_orders: permissions.executeOrders === true,
        p_view_orders: permissions.viewOrders === true,
        p_view_positions: permissions.viewPositions === true,
        p_view_balance: permissions.viewBalance === true,
        p_deposit_withdraw:
          accountId === "*" && permissions.depositWithdraw === true,
      }),
    },
  );

  const result = await response.json();
  if (!response.ok) {
    throw new Error(result.message ?? "API key creation failed");
  }

  return {
    publicKey: result.public_key,
    secretKey: result.secret_key,
  };
}
```

Create a key after the user has selected its scope and permissions:

```javascript theme={null}
const apiKey = await createQfexApiKey({
  accessToken: elevatedSession.access_token,
  name: "order-service",
  accountId: "11111111-1111-4111-8111-111111111111",
  permissions: {
    executeOrders: true,
    viewOrders: true,
    viewPositions: true,
    viewBalance: true,
    depositWithdraw: false,
  },
});

await saveToEncryptedCredentialStore(apiKey);
```

The `accountId` value must be one of:

* `*` for all primary accounts and subaccounts owned by the user
* The user's primary account ID
* A subaccount ID owned by the user

The deposit and withdrawal permission is available only when `accountId` is `*`. QFEX forces that permission to `false` for a key restricted to one account.

> [!WARNING]
>
> Never return the generated secret to logs, analytics, browser storage, or an
> untrusted caller. The response is the only time QFEX returns the plaintext
> secret.

### Elevate a session with TOTP

API-key creation requires recent MFA verification. If the user has a verified authenticator-app factor, challenge and verify that factor before creating the key:

```javascript theme={null}
async function qfexAuthRequest(path, { accessToken, body }) {
  const response = await fetch(`${QFEX_AUTH_URL}${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      apikey: QFEX_AUTH_CLIENT_KEY,
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify(body),
  });

  const result = await response.json();
  if (!response.ok) {
    throw new Error(result.msg ?? result.message ?? "MFA request failed");
  }
  return result;
}

export async function elevateQfexSessionWithTotp({
  accessToken,
  factorId,
  code,
}) {
  const challenge = await qfexAuthRequest(
    `/auth/v1/factors/${encodeURIComponent(factorId)}/challenge`,
    { accessToken, body: { factorId } },
  );

  return qfexAuthRequest(
    `/auth/v1/factors/${encodeURIComponent(factorId)}/verify`,
    {
      accessToken,
      body: {
        challenge_id: challenge.id,
        code,
      },
    },
  );
}
```

Use the `access_token` returned by the verification response for key creation. Obtain `factorId` from the signed-in user's verified factors. The user must provide the current authenticator code; do not store or attempt to generate it for them.

### HTTP request

The raw key-generation request is:

```http theme={null}
POST /rest/v1/rpc/generate_api_key_v3
Host: verify.qfex.com
Content-Type: application/json
apikey: <QFEX_AUTH_CLIENT_KEY>
Authorization: Bearer <MFA_ELEVATED_ACCESS_TOKEN>

{
  "p_name": "order-service",
  "p_account_id": "*",
  "p_execute_orders": true,
  "p_view_orders": true,
  "p_view_positions": true,
  "p_view_balance": true,
  "p_deposit_withdraw": false
}
```

A successful response contains `public_key` and `secret_key`. Persist the pair before discarding the response; the secret cannot be retrieved later.

### Common errors

| Error | Resolution |
| - | - |
| `no_recent_mfa_auth` | Complete a new MFA challenge and retry with the elevated access token. |
| `api_key_name_required` | Provide a non-empty `p_name`. |
| Invalid account scope | Use `*`, the user's primary account ID, or an owned subaccount ID. |
| Duplicate key name | Choose a different name for this user. |
| `401` | Sign in again or refresh the user session. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.