Skip to main content
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"

​
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.
ScopeAccess granted
accounts:readRead account details, balances, positions
accounts:writeCreate, update, and close accounts
funding:readRead ACH relationships and funding activity
funding:writeCreate ACH relationships, initiate deposits and withdrawals
trading:readRead orders and executions
trading:writePlace, modify, and cancel orders
marketdata:readAccess market data endpoints
documents:readList and retrieve documents
documents:writeUpload and email documents
webhooks:readList webhook configurations
webhooks:writeCreate, update, and delete webhooks
keys:manageGenerate 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 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).
    • 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: 
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

PracticeGuidance
Never expose keys client-sideAPI 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 environmentUse distinct key pairs for sandbox and production.
Rotate keys regularlyGenerate a new key, update your application config, then revoke the old key.
Scope keys minimallyOnly request the scopes your specific service requires.
Store secrets securelyUse a secrets manager, not environment variable files checked into source control.
Monitor for anomaliesReview your API key usage in the Partner Dashboard. Alert on unexpected spikes.

​
Error responses

HTTP statusMeaning
401 UnauthorizedMissing, invalid, or revoked API key/secret
403 ForbiddenKey is valid but lacks the required scope for this endpoint
See Error Codes for the full list of API error responses.