Skip to content

API keys

An API key authenticates programmatic access to the DataForge public API. Every public API request is identified by a key, and the key acts on behalf of the user it belongs to. Keys are created and managed on the user card in the user list: Settings → Users, or Settings → My company for users of your own company.

General information

Property Value
Request header X-Api-Key: <key>
Keys per user At most one active key
Validity period The key does not expire; it stays valid until it is replaced by a new key or deleted
Storage Only a hash of the key is stored, and the key value is never returned in any API response
Who can create and delete keys Super administrator, Administrator
Transport HTTPS with TLS 1.2 or higher

Notes:

  • The key value is shown only at the moment it is generated. Copy it and store it in a secure place — it cannot be read out of the application later
  • A key gives access to the account without a password, so it must be handled as a credential
  • A key that has been deleted or replaced by a new one stops working immediately

Creating a key

  1. Open Settings → Users (or the user list of your own company) and open the user card for editing
  2. In the API key field click Generate API key. For a user who already has a key the button reads Generate new key
  3. Confirm the operation in the dialog. Generating a new key invalidates the previous one: every system or application that uses the old key loses API access and stops working until the key is updated in its settings
  4. Copy the generated value using the copy icon in the API key field
  5. Click Save. Until the form is saved, the new key is not applied

A key that is already saved is displayed masked in the API key field and cannot be read from there.

Deleting a key

  1. Open the user card for editing
  2. Click Delete API key and confirm the operation
  3. Click Save

After deletion, every system or application that used the key loses API access. The user can be given a new key at any time.

Using a key

The key is sent in the X-Api-Key header of every public API request, on both the v1 and the v2 surfaces:

GET /df-api/v2/projects
X-Api-Key: <key>

Requests without the header, or with a value that does not match a stored key, are rejected with 401. Base URLs for the on-premises and cloud deployments are listed on the section landing page.

What a key gives access to

A key does not have permissions of its own — it resolves to the account it was generated for and to that account's project access:

Rule Behaviour
Account status The account must be active. A blocked or deactivated account cannot be used, even with a valid key
Project scope The key inherits the project access of its owner. Endpoints addressed to a single project return 404 Not Found when the owner has no access to that project — the existence of the project is not disclosed
Project lists GET /projects returns only projects the owner can access; the other projects are excluded from the page and from the total count
Read and write The v1 endpoints are read-only. The v2 endpoints also allow creating, updating, and deleting data, exporting and importing versions, and managing Git connections
Write access Writing to the RMD and the data model requires the owner's effective project role to be developer or higher; a lower level is rejected with 403
Access management The v2 project access and ownership endpoints additionally require the owner to be the project owner or a user with the Administrator or Super administrator role
License The whole public API is available only while the company holds a valid license
IP filtering The company IP whitelist and blacklist apply to key-authenticated requests exactly as they do to interactive logins

Request limits

Surface Limit
/df-api/v1 100 requests per 60 seconds per key
/df-api/v2 100 requests per 60 seconds per key

The limit is shared by both versions and counted per key value. Every response carries the current counter state in the X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers (the reset moment as a Unix timestamp). When the limit is exceeded, the request is rejected with 429 Too Many Requests and the code DF_API.RATE_LIMIT_EXCEEDED; wait until the moment in X-RateLimit-Reset and retry.

Authentication errors

Code HTTP When it is returned
API_KEY.KEY_MISSING 401 The X-Api-Key header was not sent
API_KEY.INVALID_KEY 401 The key does not match any stored key — for example, it was deleted or replaced by a new one
API_KEY.AUTH_FAILED 401 Authentication failed for a general reason
API_KEY.INVALID_ENCRYPTED_API_KEY 400 The transmitted key could not be decoded
API_KEY.ACCOUNT_LOCKED 403 The key owner's account is not active
API_KEY.IP_BLOCKED 403 The client IP is on the company blacklist or outside its whitelist
API.NOT_AVAILABLE_WITHOUT_VALID_LICENSE 403 The company has no valid license
DF_API.RATE_LIMIT_EXCEEDED 429 The per-key request limit was exceeded (v1 and v2)

Audit

Every public API request is recorded in the audit log under the API access category, together with its outcome:

  • A successful request is recorded as a successful API access
  • A denied or failed request is recorded as a failed API access, with the reason (missing or invalid key, blocked account, blocked IP, invalid license, exceeded request limit) appended to the entry
  • Every successful write through the v2 API additionally stores a snapshot of the affected object before and after the change

Each entry holds the key owner's email, the client IP address, the company, the API name and version, and the endpoint. The audit log is available in Settings → Audit log to the Administrator and Super administrator roles.