Documentation

Appearance

Organisation API keys ​

Organisation API keys authenticate supported Gateway and product integrations. They are different from agent provisioning keys and user sessions.

Create a key ​

  1. Open the organisation API key settings.
  2. Name the key for one workload and environment.
  3. Choose the narrowest scope offered by the editor.
  4. Create the key and copy the plaintext value immediately.
  5. Store it in a secret manager and test the intended endpoint.

The plaintext secret is shown once. Dataplicity stores a hash for later verification. Never place a key in source control, a device image readable by customers, frontend code, screenshots, tickets, or logs.

The key editor lists the scopes available to your organisation, including inventory read and supported log-ingestion access. A scope does not make a private dashboard endpoint part of the public API.

Broad organisation write covers endpoints that do not declare a narrower write scope. Avoid it when a purpose-specific scope exists.

Rotate without downtime ​

  1. Create a second key with the same minimal purpose.
  2. Update the workload's secret.
  3. Verify successful requests and failure reporting.
  4. Disable or revoke the old key.
  5. Review logs and audit history for unexpected use.

Use separate keys for development, CI, manufacturing, log forwarding, and production integrations. Rotation should not depend on discovering every consumer of one shared credential.

Respond to exposure ​

Disable or revoke the key immediately, create a replacement only if the workload is still trusted, inspect access and log history, and rotate downstream credentials that may have appeared in requests.

Use the endpoints in the Gateway API reference and documented product integrations. These are the stable contracts for external integrations.