Overview

Agent quickstart

Complete a real OAuth PKCE flow, discover released tools and call a Fullness read operation.

1. Read the live server contract

Do this first in every environment. It prevents clients from assuming that a documented capability has been released.

Shell

curl --fail --silent \
  https://api.allfullness.com/api/agent/.well-known/oauth-authorization-server

curl --fail --silent \
  https://api.allfullness.com/api/agent/openapi.json

2. Generate PKCE and state

Fullness requires authorization code flow with PKCE S256. Keep the verifier server-side until the callback.

Node.js

import { createHash, randomBytes } from 'node:crypto';

const verifier = randomBytes(48).toString('base64url');
const challenge = createHash('sha256').update(verifier).digest('base64url');
const state = randomBytes(32).toString('base64url');

// Store verifier + state in the user's server-side login session.

3. Send the user to Fullness

Node.js

const authorize = new URL(
  'https://api.allfullness.com/api/agent/oauth/authorize'
);
authorize.search = new URLSearchParams({
  client_id: process.env.FULLNESS_CLIENT_ID,
  redirect_uri: 'https://your-app.example/oauth/fullness/callback',
  response_type: 'code',
  code_challenge: challenge,
  code_challenge_method: 'S256',
  scope: 'actions:read tool:get_account_balances privacy:shareAccounts',
  purpose: 'Show the user their connected account balances',
  state,
}).toString();

response.redirect(authorize.toString());

4. Exchange the callback code

Reject a callback whose state does not match the value stored in the login session.

Shell

curl --request POST \
  https://api.allfullness.com/api/agent/oauth/token \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'code=CODE_FROM_CALLBACK' \
  --data-urlencode 'redirect_uri=https://your-app.example/oauth/fullness/callback' \
  --data-urlencode 'code_verifier=YOUR_ORIGINAL_VERIFIER'

5. Execute a released read

Shell

curl --request POST \
  https://api.allfullness.com/api/agent/external/v1/actions/get_account_balances/execute \
  --header "authorization: Bearer $FULLNESS_ACCESS_TOKEN" \
  --header 'content-type: application/json' \
  --data '{"arguments":{}}'

A successful response includes both the canonical result and a traceable Fullness action:

JSON

{
  "result": {
    "ok": true,
    "canonicalToolName": "get_account_balances",
    "contractVersion": "1.0.0",
    "data": {},
    "evidence": {}
  },
  "action": {
    "id": "action_…",
    "status": "succeeded",
    "runId": "run_…",
    "stepId": "step_…",
    "activityUrl": "https://app.allfullness.com/…"
  }
}

6. Handle lifecycle states

Reads may complete immediately. Draft/write operations can return HTTP 202 with waiting_approval. Open the returned Fullness approval URL for the user and poll the action URL; never collect approval credentials inside your application.

Read the complete action lifecycle →