Authentication

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:

curl https://dev-tapp-api.tappengine.com/v1/accounts \
  -H "X-API-Key: bm_key_abc123" \
  -H "X-API-Secret: bm_secret_xyz789"

The same key pair can alternatively be sent as HTTP Basic auth — Authorization: Basic base64(api_key:api_secret):

curl https://dev-tapp-api.tappengine.com/v1/accounts \
  -u "bm_key_abc123:bm_secret_xyz789"

Note: Authorization: Bearer <token> is reserved for user-facing OAuth/JWT flows (e.g., the CLI’s device login). Passing an API key as a Bearer token is not supported.

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:

Send an email request to the Buildmarkets team at support@buildmarkets.ai or contact your designated Relationship Manager.
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).
- Label: A descriptive label for the key pair (e.g., sandbox-backend or prod-trading-engine).
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:

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:

{
  "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:

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:

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.

Core Concepts

Infrastructure

How authentication works

API key scopes

Requesting API keys

Via email request

Via the API

Listing API keys

Revoking API keys

Security best practices

Error responses

​How authentication works

​API key scopes

​Requesting API keys

​Via email request

​Via the API

​Listing API keys

​Revoking API keys

​Security best practices

​Error responses

How authentication works

API key scopes

Requesting API keys

Via email request

Via the API

Listing API keys

Revoking API keys

Security best practices

Error responses