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

# Authentication

> How Buildmarkets API key authentication works, including generating, listing, and revoking scoped key pairs and security best practices.

The Buildmarkets API uses **API key authentication**. Every request must include a valid key pair. This page explains how authentication works, how to generate and manage keys, and security best practices.

## How authentication works

Every Buildmarkets API request requires two HTTP headers:

```
X-API-Key: <your-api-key>
X-API-Secret: <your-api-secret>
```

Both values are required on every request. There is no session token or cookie mechanism — each request is independently authenticated.

**Example request:**

```bash theme={"system"}
curl https://dev-tapp-api.tappengine.com/v1/accounts \
  -H "X-API-Key: bm_key_abc123" \
  -H "X-API-Secret: bm_secret_xyz789"
```

## API key scopes

When generating an API key, you assign it one or more **scopes** that control which endpoints it can access. This follows the principle of least privilege.

| Scope             | Access granted                                              |
| ----------------- | ----------------------------------------------------------- |
| `accounts:read`   | Read account details, balances, positions                   |
| `accounts:write`  | Create, update, and close accounts                          |
| `funding:read`    | Read ACH relationships and funding activity                 |
| `funding:write`   | Create ACH relationships, initiate deposits and withdrawals |
| `trading:read`    | Read orders and executions                                  |
| `trading:write`   | Place, modify, and cancel orders                            |
| `marketdata:read` | Access market data endpoints                                |
| `documents:read`  | List and retrieve documents                                 |
| `documents:write` | Upload and email documents                                  |
| `webhooks:read`   | List webhook configurations                                 |
| `webhooks:write`  | Create, update, and delete webhooks                         |
| `keys:manage`     | Generate and revoke API keys                                |

> **Important:** "Assign only the scopes your application needs. A compromised key with narrow scopes limits your exposure."

## Requesting API keys

### Via email request

Buildmarkets API keys are provisioned and distributed via email. To request a new API key pair:

1. Send an email request to the Buildmarkets team at [support@buildmarkets.ai](mailto:support@buildmarkets.ai) or contact your designated Relationship Manager.
2. In your request, include the following details:
   * **Environment**: Whether you need keys for `sandbox` (testing) or `production` (live).
   * **Scopes**: The specific permission scopes your integration requires (see [API key scopes](#api-key-scopes)).
   * **Label**: A descriptive label for the key pair (e.g., `sandbox-backend` or `prod-trading-engine`).
3. Key requests are processed in regular batches. Once generated, your API key pair will be securely transmitted to your registered technical contact via encrypted email.

### Via the API

You can also generate keys programmatically using an existing key that has the `keys:manage` scope:

```bash theme={"system"}
curl -X POST https://dev-tapp-api.tappengine.com/v1/keys \
  -H "X-API-Key: YOUR_EXISTING_KEY" \
  -H "X-API-Secret: YOUR_EXISTING_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "backend-service-prod",
    "scopes": ["accounts:read", "trading:write", "marketdata:read"]
  }'
```

**Response:**

```json theme={"system"}
{
  "id": "key-001",
  "label": "backend-service-prod",
  "api_key": "bm_key_abc123",
  "api_secret": "bm_secret_xyz789",
  "scopes": ["accounts:read", "trading:write", "marketdata:read"],
  "created_at": "2025-06-01T12:00:00Z"
}
```

> **Security note:** "The `api_secret` is only returned once at creation time. Store it immediately in a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault). It cannot be retrieved again — if lost, revoke the key and generate a new one."

## Listing API keys

Retrieve all keys associated with your partner account:

```bash theme={"system"}
curl https://dev-tapp-api.tappengine.com/v1/keys \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

The response lists key metadata (ID, label, scopes, creation date) but **never** includes the secret value.

## Revoking API keys

Revoke a key that is no longer needed or may be compromised:

```bash theme={"system"}
curl -X DELETE https://dev-tapp-api.tappengine.com/v1/keys/{keyId} \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Secret: YOUR_API_SECRET"
```

Returns `204 No Content` on success. Revoked keys are immediately invalidated — any in-flight requests using the revoked key will fail with `401 Unauthorized`.

## Security best practices

| Practice                              | Guidance                                                                                                                                |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **Never expose keys client-side**     | API keys should only be used in server-side code. Never include them in mobile app bundles, browser JavaScript, or public repositories. |
| **Use separate keys per environment** | Use distinct key pairs for sandbox and production.                                                                                      |
| **Rotate keys regularly**             | Generate a new key, update your application config, then revoke the old key.                                                            |
| **Scope keys minimally**              | Only request the scopes your specific service requires.                                                                                 |
| **Store secrets securely**            | Use a secrets manager, not environment variable files checked into source control.                                                      |
| **Monitor for anomalies**             | Review your API key usage in the Partner Dashboard. Alert on unexpected spikes.                                                         |

## Error responses

| HTTP status        | Meaning                                                     |
| ------------------ | ----------------------------------------------------------- |
| `401 Unauthorized` | Missing, invalid, or revoked API key/secret                 |
| `403 Forbidden`    | Key is valid but lacks the required scope for this endpoint |

See Error Codes for the full list of API error responses.