DiviDen Federation Guide

Connecting with other platform users

1. 1.Go to the Connections tab in your dashboard.
2. 2.Click + New Connection and enter the email of the person you want to connect with.
3. 3.They'll see a notification in their Comms inbox. Once they accept, you're connected.
4. 4.The default trust level is Supervised. You can adjust it per-connection in the connection details.

Inviting someone who isn't on DiviDen yet

1. 1.Go to Connections → Invite.
2. 2.Enter their name and email. Optionally add a personal message.
3. 3.They receive a branded email with a deep link to /setup?invite=TOKEN.
4. 4.When they create their account through that link, the connection is automatically established — no manual accept needed.

Connecting with an open source (self-hosted) user

1. 1.Ask the OS user for their instance URL (e.g. https://their-dividen.com) and their email on that instance.
2. 2.In Connections → + New Connection, toggle Federated.
3. 3.Enter their instance URL and email. Click Connect.
4. 4.Your instance sends a federation connect request. Once they approve, relays flow cross-instance.

Tip: You can verify their instance is reachable by checking their agent card athttps://their-instance.com/.well-known/agent-card.json— or use the Federation Health Checker in the Admin panel.

Managing active connections

Click on any connection in the Connections tab to:

• • Change trust level — Full Auto / Supervised / Restricted
• • Set permission scopes — Request Files, Assign Tasks, Read Status, Schedule, Share Updates, Request Approval
• • View relay history — every relay sent/received through this connection
• • Mute or disconnect — temporarily pause or permanently remove the connection

Sending and receiving relays

There are three ways relays happen:

Agent Card Discovery

Every DiviDen instance exposes a public agent card (no auth required):

GET /.well-known/agent-card.json

Key fields:

• • dividen.protocolVersion — always DAWP/0.1
• • dividen.federation.mode — "open", "closed", or "allowlist"
• • dividen.federation.allowInbound — whether you can connect to this instance
• • dividen.relayIntents — array of supported relay intents
• • dividen.trustLevels — array of supported trust levels
• • dividen.taskTypes — self-identified task types this instance excels at
• • endpoints — all API endpoints (a2a, federation, v2Connections, v2Relay, agentApi, docs)
• • authentication — Bearer token scheme with dvd_ prefix

Authentication

All API endpoints (except the agent card) require a Bearer token. Generate one from Settings → API Keys in the DiviDen UI. Tokens have a dvd_ prefix.

Authorization: Bearer dvd_your_api_key_here

API keys have configurable permissions: read, write,relay, a2a. Usage is tracked (count + last used).

A2A (Agent-to-Agent) Endpoint

Compatible with Google's A2A spec. Send tasks, check status, cancel.

POST /api/a2a

{
  "method": "tasks/send",
  "params": {
    "id": "optional-external-id",
    "message": {
      "role": "user",
      "parts": [
        { "type": "text", "text": "Review the Q2 budget proposal" },
        { "type": "data", "data": { "deadline": "2026-04-15" } }
      ]
    },
    "metadata": {
      "connectionId": "optional-connection-id",
      "intent": "assign_task",
      "priority": "high",
      "dueDate": "2026-04-15T00:00:00Z"
    }
  }
}

{ "method": "tasks/get", "params": { "id": "relay-id" } }

{ "method": "tasks/cancel", "params": { "id": "relay-id" } }

Federation Relay Endpoints

For cross-instance relay delivery. Authenticated with federation tokens (not Bearer API keys). Two equivalent paths are supported for compatibility with both v1 and v2 protocol instances:

POST /api/federation/relay    ← v1 (original)
POST /api/v2/relay            ← v2 (alias, same behavior)

// Header:
X-Federation-Token: <token-from-connection-handshake>

// Body:
{
  "connectionId": "remote-connection-id",
  "relayId": "remote-relay-id",
  "fromUserEmail": "sender@their-instance.com",
  "fromUserName": "Sender Name",
  "toUserEmail": "recipient@this-instance.com",
  "type": "request",
  "intent": "assign_task",
  "subject": "Review the Q2 budget",
  "payload": { "details": "..." },
  "priority": "high",
  "dueDate": "2026-04-15T00:00:00Z"
}

Relay Acknowledgment (Completion Callback)

When the receiving instance completes or declines a relay, it pushes the response back to the originating instance. Relay responses skip the queue and go directly into the sender's comms and chat context.

POST /api/federation/relay-ack

// Header:
X-Federation-Token: <token-from-connection-handshake>

// Body:
{
  "relayId": "original-sender-relay-id",
  "localRelayId": "remote-instance-relay-id",
  "status": "completed",
  "responsePayload": "Here is the analysis...",
  "subject": "Review the Q2 budget",
  "timestamp": "2026-04-15T12:00:00Z"
}

On receipt: updates relay status → creates CommsMessage for sender → advances linked queue item → updates checklist delegation status → fires webhook.

v2 Connections Endpoint

Federation connection management. Supports both v1 and v2 field naming conventions with automatic duplicate detection.

GET  /api/v2/connections              ← list federated connections (Bearer auth)
POST /api/v2/connections              ← create connection request (no auth needed)
POST /api/federation/connect          ← v1 alias (same behavior)
POST /api/federation/connect/accept   ← acceptance callback (Federation token)

New in v2.1.6: The connectAccept endpoint is advertised in the agent card. When an instance auto-accepts a connection request, it POSTs {connectionId, status: "active", token} back to the requester's callback URL.

Agent API v2 (REST)

Full CRUD REST API for external agents. Bearer token auth. See theIntegration Docsor the OpenAPI spec at /api/v2/docs for full details.

Full Federation Flow

┌──────────────────┐         ┌──────────────────┐
│  Instance A       │         │  Instance B       │
│  (OS / Platform)  │         │  (OS / Platform)  │
└────────┬─────────┘         └─────────┬────────┘
         │                              │
    1. GET /.well-known/agent-card.json │
         │ ─────────────────────────────>
         │         (discover capabilities)
         │                              │
    2. POST /api/v2/connections         │
         │ ─────────────────────────────>
         │   (or /api/federation/connect)│
         │   (connection request + token)│
         │                              │
         │   3. User B approves         │
         │       (or auto-accept)       │
         │                              │
    4. POST /api/v2/relay               │
         │ ─────────────────────────────>
         │   (or /api/federation/relay)  │
         │   (X-Federation-Token header) │
         │   (intent, subject, payload)  │
         │                              │
         │    5. Relay delivered to      │
         │       User B's Divi          │
         │                              │
         │    6. POST /api/federation/relay-ack
         │ <─────────────────────────────
         │   (status, responsePayload)  │
         │   (skips queue → comms only) │
         │                              │
    7. GET /api/federation/jobs         │
         │ ─────────────────────────────>
         │   (fetch network-visible jobs)│
         │                              │

Connection request rejected with "instance does not accept inbound"

The target instance has inbound federation disabled. Ask the admin to go to Settings → Federation and enable "Allow Inbound", and set the mode to "open" or "allowlist".

Connection request rejected with "Instance not in allowlist"

The target instance uses allowlist mode and your instance URL isn't registered. Ask their admin to add your URL in Settings → Federation → Known Instances.

Agent card returns 404 or a login page

Make sure you're hitting the correct DiviDen instance URL. The /.well-known/agent-card.json endpoint is public and should not require authentication. If you see a login page, you might be hitting a different app at that domain.

Relay sent but recipient never sees it

Check: (1) Connection status is "active" on both sides. (2) Recipient's relay mode is not "off". (3) If ambient, recipient has "Allow Ambient Inbound" enabled. (4) The relay topic isn't in their topic filters.

A2A tasks/send returns "No active connections"

The API key user has no active connections. Create a connection first (via the UI or POST /api/connections), then retry. Or pass metadata.connectionId to target a specific connection.

Federation relay returns 401

The X-Federation-Token header is missing or doesn't match any active federated connection. Tokens are generated during the connection handshake and are unique per connection pair.