Authentication
All public Diafunc APIs share a single authentication model based on API tokens. This page describes how to obtain a token, how to present it on a request, which scopes control what operations, and the shape of the error responses returned by every API.
API tokens
API tokens are structured, prefixed strings of the form dfat_<id>_<secret> — a dfat_ prefix, a token id, and a secret part; callers treat the secret as opaque. They are issued by the Admin API and are bound to a single project. Each token also carries a set of scopes that determine which operations it can perform.
A token is presented on every request as a Bearer token in the Authorization header.
Example request
Web sessions
User sessions from the Diafunc web application use a separate mechanism: OpenID Connect with ES256-signed JWTs issued by auth.diafunc.com. The signing keys are published at auth.diafunc.com/.well-known/jwks.json and rotated periodically. API tokens remain the right choice for programmatic access from external systems.
Scopes
The following scopes can be granted to an API token. Scopes are additive: a token with storage:write also implicitly allows storage:read operations on the same resource.
| Scope | Grants |
|---|---|
| project:read | Read project metadata, members, and settings. |
| project:write | Modify project metadata, members, and settings. |
| storage:read | Read entities, links, events, tables, and notebooks of a project. |
| storage:write | Create, update, and delete project content. |
| evaluation:read | Inspect evaluations, outputs, and logs. |
| evaluation:execute | Start and stop evaluations, manage triggers. |
Project token scope
A project-scoped token grants access only to the project it was issued for, limited further by the scopes granted to it.
Tokens can be issued, listed, and revoked through the Admin API. Rotating a token means issuing a new one with the same scopes and revoking the old one once the new one has been deployed.
Errors
Error responses share a common JSON shape across all APIs. The HTTP status is repeated in the body for convenience; error carries a short identifier and message a human-readable explanation.
Example error response
| Status | Meaning |
|---|---|
| 400 Bad Request | The request body or parameters did not validate. |
| 401 Unauthorized | The token is missing, invalid, revoked, or the owning user is locked. |
| 403 Forbidden | The token is valid but lacks the scope or permission for the requested operation. |
| 404 Not Found | The resource does not exist or is not visible to the caller. |
| 429 Too Many Requests | Rate limit exceeded for authentication or enumeration endpoints. |
| 500 Internal Server Error | Unexpected server-side failure. |