1. Assign an integration owner

Open “Settings → Access → API clients” as an administrator. Create a separate client for each external system and environment: you can then rotate a key or disable one channel without stopping the others. Enter a recognizable name and an owner user. The key operates only within that user's permissions.

Select “Write” for data intake and “Read” for statuses, results and publication endpoints. Write is available only for flows the owner can execute; read, for flows they can view. Publication with execution on demand also requires the owner's execution permission. Disabling the owner or removing their permission affects the key immediately.

2. Limit lifetime, network access and load

Choose an expiry date, valid through the end of that UTC day, no more than three years ahead. Add permitted IPv4/IPv6 addresses or CIDR networks, one per line. IP access and HMAC are independent settings: “Any IP address” disables IP filtering. Signing is enabled by default; keeping it enabled is recommended, especially without IP restrictions. Set requests per minute. The section's overall API limit applies as well.

Save the client and transfer the generated key through your secure channel. Do not put it in browser code, a public repository or a URL. Data Bridge generates the key; arbitrary custom keys are unsupported. Displaying a full key is recorded in the audit. Use an environment variable for examples and tests.

3. Sign the exact HTTP request

Send the key in Authorization: Bearer ... or X-API-Key. HMAC additionally needs X-UBC-Timestamp containing Unix seconds and X-UBC-Signature: v1=<hex>. Compute HMAC-SHA256 using the client key over four newline-separated values: timestamp, uppercase HTTP method, path including query string, and the SHA-256 hex digest of the exact body bytes.

Clock difference from the server must not exceed five minutes. Preserve parameter order, encoding and the installation prefix. Do not modify the body after signing: differently formatted JSON has a different hash. For GET, hash empty bytes. The secret is the API client's key, not the callback secret.

4. Check access with ping

In a Python environment with requests installed, set UBC_API_KEY and UBC_API_PING_URL. The latter is the complete HTTPS address of /api/v1/ping, including the required prefix. This example prepares the request before signing, so it uses the actual encoded path; redirects are disabled.

import hashlib, hmac, os, time
from urllib.parse import urlsplit
import requests

key = os.environ["UBC_API_KEY"]
url = os.environ["UBC_API_PING_URL"]
request = requests.Request("GET", url).prepare()
body = request.body or b""
if isinstance(body, str):
    body = body.encode("utf-8")
parts = urlsplit(request.url)
path = parts.path + ("?" + parts.query if parts.query else "")
timestamp = str(int(time.time()))
canonical = "\n".join([
    timestamp, request.method, path,
    hashlib.sha256(body).hexdigest()
])
signature = hmac.new(key.encode("utf-8"),
                     canonical.encode("utf-8"),
                     hashlib.sha256).hexdigest()
request.headers.update({
    "Authorization": "Bearer " + key,
    "X-UBC-Timestamp": timestamp,
    "X-UBC-Signature": "v1=" + signature,
})
with requests.Session() as session:
    response = session.send(request, timeout=30,
                            allow_redirects=False)
    print(response.status_code, response.text)

Check the returned client, server time, expiry and permissions. Then call GET /api/v1/flows and confirm that only agreed flows are accessible. Changing the address requires a new signature. For POST, prepare the body once, sign its bytes and send those exact bytes.

5. Retries, rotation and diagnostics

A signature is accepted once: replay returns 409 API_SIGNATURE_REPLAY. Sign every poll or delivery retry again; respect Retry-After to avoid repeating an identical GET within the same second. Preserve the delivery's Idempotency-Key: it prevents duplicate execution, while HMAC protects each individual HTTP request.

401 generally concerns the key, expiry or signature; 403, IP or permissions; 429, rate limits. Read the specific response code and audit record. Repeated authentication failures temporarily block the IP address.

For rotation, the administrator generates a new key and saves the client: the previous key stops working. In “API → My API keys”, where the role permits, owners can view and renew their keys; self-service rotation takes effect immediately. After replacement, verify ping and one permitted scenario, then remove the old secret from the external system.

For controlled history access, use GET /api/v1/flows/{flow}/runs. The completed run’s result list is available at /api/v1/flows/{flow}/results?run=latest; a specific table at /api/v1/flows/{flow}/results/{block}?format=json&offset=0&limit=100. Select identifiers from the response rather than another example. Pin a specific run when reading several tables from one result: latest can change after a new execution. These routes require flow “Read” permission, and every address and page needs its own signature.