Authentication and keys

Este artículo aún no está disponible en español; se muestra a continuación en inglés.

API keys

The API authenticates with secret keys that belong to your organisation. A signed-in user creates them in the app under Organisation → API keys, gives each a name and chooses its scopes. A key acts for the organisation, not for the person who created it, and sees exactly that organisation’s models, batteries and passports.

Keys look like dpp_live_ or dpp_test_ followed by 40 hexadecimal characters. The full key is shown exactly once, when it is created. We store only its SHA-256 hash, so nobody — including us — can show it to you again. We also keep the first few characters of each key, so keys can be told apart.

# Illustrative — not a real key.# dpp_live_ + 40 hex characters. The first part (dpp_live_3f9a) is kept to tell keys apart.dpp_live_3f9a0c5e7b1d24a68e0f9c3b5d7a1e2f4c6b8d0a

Live and test keys

Both read your real data. Develop and run CI with a test key, deploy with a live key — see test keys and dry runs.

Sending the key

Send the key as a bearer token in the Authorization header of every request. Keys work only on /v1/*paths; the app’s own endpoints do not accept them, and the public resolver does not need one.

curl "https://dppapi-production.up.railway.app/v1/me" \-H "Authorization: Bearer $DPP_API_KEY"

A request with no key, a malformed key, an unknown key or a revoked key is answered with 401 unauthorized. GET /me is the simplest way to check a key: it returns the key, its scopes and mode, your organisation, plan, usage and rate limit.

Scopes

Each key carries one or both scopes. The scope is checked against the HTTP method of the request:

A write with a key that only has read is refused with 403 and insufficient_scope. DELETE is refused for every key, whatever its scopes, with 403 and method_not_allowed_for_api_keys — see why there is no DELETE.

{"error": "insufficient_scope","message": "This API key does not have the \"write\" scope.","request_id": "3f1c2a9e-8d4b-4c6f-9e2a-7b5d1c0e8f34"}

Rotation and revocation

Revoking a key in the app takes effect immediately: the next request with it is answered with 401. A revoked key cannot be restored. To rotate without downtime, create the new key, deploy it, confirm traffic with GET /me, then revoke the old one.

Good practice

• One key per integration (ERP, MES, BMS gateway), named after it, so one can be revoked without stopping the others.
• Give each key the least scope it needs: a reporting job or dashboard only needs read.
• Keep keys in a secret manager or environment variable, never in source code, front-end bundles or mobile apps.
• Call the API from your servers. Keys are organisation-wide secrets and must not reach a browser.