Authentication
The VDF AI API authenticates requests with access tokens. Sign in with a user account to obtain a token, then send it in the Authorization header of each request as a bearer token.
One token works across the platform: the token issued at sign-in is accepted by every API in this reference, without any exchange step. Requests without a valid token fail with 401 Unauthorized.
Make every request over HTTPS, so the token is never sent in clear text.
curl "$VDF_BASE_URL/api/auth/session" \
-H "Authorization: Bearer $VDF_ACCESS_TOKEN"Obtain an access token
Call Sign in with the email address and password of a VDF AI user. The response contains access_token together with a summary of the signed-in user.
Treat the token as opaque: send it exactly as you received it, and don't parse or modify it.
curl -X POST "$VDF_BASE_URL/api/auth/login" \
-H "Content-Type: application/json" \
-d '{
"email": "ada@example.com",
"password": "<PASSWORD>"
}'{
"success": true,
"access_token": "<ACCESS_TOKEN>",
"user": {
"id": 42,
"email": "ada@example.com",
"name": "Ada Lovelace"
}
}Token lifetime
Access tokens are valid for 24 hours from sign-in. When a token expires, requests return 401; sign in again to obtain a new token.
Long-running integrations should expect this: on a 401, obtain a fresh token once and retry the request, rather than signing in before every call.
Single sign-on accounts
If your organisation signs in to VDF AI with Microsoft Entra ID, people authenticate through the browser and never hand a password to VDF AI.
For unattended, server-to-server integrations, ask your administrator for a dedicated account for the integration, with only the permissions it needs. A dedicated account keeps the integration's access reviewable and lets you revoke it without affecting a person.
Browser sessions
When a browser signs in on your deployment's domain, the sign-in response also sets an HttpOnly session cookie. The VDF AI portal uses it to share one session across its applications.
Browser applications served from the same domain can rely on that cookie by sending requests with credentials included. Applications served from another origin must be allowed by your deployment's cross-origin configuration; ask your administrator.
const response = await fetch('/agent-hub-api/api/agent/list', {
credentials: 'include',
});
const agents = await response.json();Permissions and visibility
A token acts with the permissions of the user it was issued to.
- Resources are visible to their owner, and to others when they are shared with the owner's company or with specific users and groups.
- A resource you cannot see behaves as if it does not exist: requests for it return
404, so its existence is not disclosed. - Your administrator can require a capability, granted to roles, for some operations — for example creating workspaces, registering MCP servers, or defining HTTP tools. When a required capability is missing, the request fails with
403. - Administration endpoints require an administrator account. They are grouped under Administration in each API and marked under Permission on every endpoint; other accounts receive
403.
Keep tokens secret
An access token carries the full access of its user. Store tokens in a secrets manager or your platform's credential store — never in source code, URLs, query strings, or logs, and never in browser storage that page scripts can read.
Use a separate account for each integration, so that each one's access can be reviewed and revoked independently.