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
Match the credential to the consumer #
| Consumer | Credential and boundary |
|---|---|
| Developer integration / hosted MCP | Organisation API key; explicit operation scopes and Device Class ownership |
| Main app and mobile app | Signed-in user access token; user roles and object visibility |
| Customer Portal | Portal user token on the matching whitelabel host and /api/portal/; core user IDs are a separate identity namespace |
| Network Connector | Connector machine credential; live policy user, allowed devices and ports, and session version |
| Named tunnel publisher | TunnelPublisher scoped credential or signed-in user; name, port and generation checks |
| Named tunnel consumer / administration | Signed-in user; consume or manage permission. Publisher credentials cannot consume or administer |
| Device agent | Per-device API key or agent JWT on the device plane; a hashed path must match the authenticated device |
| Visitors kiosk | VisitorTerminal enrolment credential bound to a live terminal, organisation and site |
| Files sync instance | Revocable Files credential bound to its owner and organisation; no general API authority |
The interactive reference covers organisation-key integrations plus unauthenticated health. Other consumers have different contracts even when they share backend infrastructure. Gateway does not serve the main website, legacy mobile root routes, device-agent root routes, or portal-prefixed aliases. Those retain their own application or device hosts.
Explicit invalid API-key credentials are rejected. Do not mix a Bearer Authorization header with X-API-Key: Authorization selects the authentication scheme.
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:
| Scope | Allows |
|---|---|
inventory:read | Read organisation device inventory |
developer:devices:read | Read developer device catalog, wormhole status, timeline and developer logs |
developer:devices:write | Update device fields and related safe writes |
fleet_jobs:read / fleet_jobs:write | List/inspect or cancel fleet jobs; creation currently requires a signed-in user |
monitors:read / monitors:write | Endpoint and heartbeat monitors |
incident_automation:read / incident_automation:write | Incident automation rules and insights |
mcp:read / mcp:write | Convenience scopes for the hosted MCP |
logs:forwarder | Ingest log lines from HTTPS or syslog forwarders |
org:write | Broad write access where a narrower scope is not declared |
Prefer the narrowest scope that covers the integration. mcp:read / mcp:write are aliases intended for Cursor and similar agents; backend HTTP integrations should usually request the explicit developer or product scopes.
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:
| Identifier | Used in | Purpose |
|---|---|---|
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/403responses - Do not commit keys to source control