Documentation

Appearance

API authentication ​

The Gateway API uses organisation API keys for server-to-server integrations. Keys represent organisation-level authority - never expose them in browser or mobile clients.

Send your API key ​

Primary header:

Authorization: ApiKey <your-organisation-api-key>

Fallback (for clients that cannot set Authorization):

X-API-Key: <your-organisation-api-key>

Invalid auth formats ​

Do not use these for Gateway API keys:

  • Bearer <key>
  • Token <token>
  • HTTP Basic auth
  • Query-string API keys

Obtain an API key ​

Create an organisation API key from your Dataplicity account dashboard. Store it in server-side secret storage (environment variable, secrets manager, or vault).

Rotate keys on a schedule. Revoke immediately if a key may have been exposed.

Scopes ​

API keys carry scopes that control what each key can do. Example scopes referenced in the Gateway API:

ScopeAllows
inventory:readRead organisation device inventory
(additional scopes)Write operations, remote access, logs, automation - assign minimum required scope per integration

If a request returns 403 Forbidden, the key may lack the required scope for that endpoint.

Tenancy identifiers ​

Every scoped request uses organisation and device identifiers from your account:

IdentifierUsed inPurpose
org_hash/api/organisations/{org_hash}/…Organisation scope
device_hash/api/developer/devices/{device_hash}/, /api/remote/devices/{device_hash}/…Individual device
hash_id/api/device-classes/{hash_id}/…Device class

Persist these as stable foreign keys in your integration domain model.

Example authenticated request ​

bash
curl -s \
  -H "Authorization: ApiKey $ORG_API_KEY" \
  "https://gateway.dataplicity.com/api/developer/devices/"
shell
http GET "https://gateway.dataplicity.com/api/organisations/$ORG_HASH/devices/" \
  "Authorization: ApiKey $ORG_API_KEY"

Security requirements ​

  • Keep API keys server-side only
  • Use separate keys per environment (staging, production)
  • Log auth failures and alert on repeated 401/403 responses
  • Do not commit keys to source control