Authentication & keys

Concepts

Three credentials play a role. Two you receive from AIOTIC, one you create for AIOTIC. For a standard integration the sync key is all you need on the AIOTIC side.

Rendering diagram…

Which key opens which door.

Calls to AIOTIC: X-API-Key

Every data-plane request carries the key in a header:

GET /order_status/list HTTP/1.1
Host: acme.aiotic.ai
X-API-Key: <key>

Key	Accepted on	Who gets it
Sync key	/customer/*, /product/*, /customer-product/* only	every integration: master-data sync job, ERP-side scripts
Integration key	every endpoint	issued per project by the AIOTIC team for headless integrations and custom review UIs

Most integrations never need the integration key: master data goes in with the sync key, and orders come out through the receive endpoint that AIOTIC calls on your side. Ask your AIOTIC contact for an integration key only when you build one of the headless models.

A missing or wrong key returns 401:

{ "detail": "Invalid or missing API key" }

Two endpoints need no key: GET /healthcheck and GET /system-status.

Why two keys

The sync job often runs close to the ERP (a scheduled task, a stored procedure calling a script). Giving it the sync key means a leak there cannot read or send orders. The SDK routes master-data calls to the sync key automatically when AIOTIC_SYNC_API_KEY is set.

Calls from AIOTIC: X-API-KEY

When AIOTIC calls your endpoints (the ERP receive endpoint and the optional processing webhook) it sends the key you provided during onboarding:

POST /aiotic/orders HTTP/1.1
Host: integration.example.com
Content-Type: application/json
X-API-KEY: <the key you gave AIOTIC>

Verify it on every call, with a constant-time comparison, and reject with 401 otherwise. There is no signature or timestamp today (a signed scheme is proposed); transport security is TLS.

Tenant configuration

The tenant's ERP receive endpoint (URL, key, timeout) and the processing webhook are configured in the AIOTIC app by a tenant admin, or by the AIOTIC team during onboarding. This configuration is not reachable with API keys; hand the URL and key to your AIOTIC contact or enter them in the app's settings screen.

Handling keys safely

• Keep keys in a secret store or environment variables — never in source code, never in a browser or mobile app.
• Use one key per service. Rotate on staff changes; the sync key is admin-rotatable, the integration key is rotated by the AIOTIC team on request.
• Log the fact that a request was rejected, never the key value.
• In the SDK, Settings.from_env() reads AIOTIC_API_KEY, AIOTIC_SYNC_API_KEY, AIOTIC_ERP_RECEIVE_KEY and AIOTIC_WEBHOOK_KEY.

Example

curl

curl -s https://acme.aiotic.ai/customer/list?size=5 -H "X-API-Key: $AIOTIC_SYNC_API_KEY"

Python SDK

from aiotic import AioticClient

client = AioticClient(base_url="https://acme.aiotic.ai", api_key="…integration…", sync_api_key="…sync…")
client.customers.list(size=5)      # sent with the sync key
client.orders.list(size=5)         # sent with the integration key