# Fullness Developers

Canonical, contract-backed documentation for Fullness agent integrations, Credit APIs and Financial Passport verification.

Canonical API base: https://api.allfullness.com/api/agent
Live OpenAPI 3.1: https://api.allfullness.com/api/agent/openapi.json

## Home

Source: https://developers.allfullness.com

Integrate governed agent actions, credit decisions and consent-bound Financial Passport verification from one developer homebase.

Controlled public beta 
One homebase. Three governed product families. 
Use Agent Actions for consented finance workflows, the Credit API for approved partner decisions, and Financial Passport for holder-approved credential verification. 
Choose a product Understand access 
Availability is explicit Agent operations are governed by the live release contract. Credit and Passport operations require an approved private-beta partner, an enabled environment, an active API key and the contracted compliance settings. 
Choose a product 
Controlled public beta Agent Platform Execute governed reads and approval-bound actions through HTTP, MCP or A2A. 
Private beta Credit API Request signed score attestations and health signals for consented subjects. 
Private beta Financial Passport Create holder-consent requests and verify threshold-based financial credentials. 
Private beta Credit products Discover products, check eligibility and integrate approved lending lanes. 
One trust model Agent grants bind client, user, workspace, purpose and scopes. Credit data release requires an approved partner, accepted DPA, allowed jurisdiction and purpose. Financial Passport requests are fulfilled by the holder and expose verified claims, never authority to act. Consequential actions keep their Fullness-hosted approval boundary. Unknown, prohibited, expired, revoked and unreleased capabilities fail closed. 
Need integration access? Registration is reviewed. Tell us which product, environment, jurisdictions, data-use purpose and security contact you need. Request developer access

## Agent quickstart

Source: https://developers.allfullness.com/quickstart

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

Before you start You need a Fullness-registered client ID, an exact registered HTTPS redirect URI and an approved scope set. Registration is currently reviewed rather than self-service. Request access if you do not have these values. 
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 Copy 
```
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 Copy 
```
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 Copy 
```
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());
```
Use only released scopes get_account_balances is a real canonical tool and is enabled in the staging default. Request it only if the live metadata/OpenAPI for your environment lists it and it was allowed for your registered client. 
4. Exchange the callback code Reject a callback whose state does not match the value stored in the login session. 
Shell Copy 
```
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 Copy 
```
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 Copy 
```
{
"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 →

## Platform concepts

Source: https://developers.allfullness.com/concepts

Understand workspaces, grants, scopes, canonical tools, action state and evidence before integrating.

Authorization boundary An external access token resolves to a grant bound to one registered client, one Fullness user, one workspace, a declared purpose and an exact scope set. It cannot be reused to cross workspace boundaries. 
Canonical tools Fullness maintains one versioned tool catalogue. OpenAPI, MCP and A2A are generated projections of that catalogue and the environment release allow-list. A tool absent from live discovery is unavailable even if it appears in source history or another environment. 
Reads, drafts and writes Kind Authority Idempotency Approval Read actions:read plus data/privacy scopes Not required None Draft/write actions:draft plus data/privacy scopes Required Fullness-hosted handoff L5/prohibited Never externally released — Cannot be requested 
Evidence and activity Every action returns identifiers and an activity URL. Results preserve the canonical tool name, contract version and evidence object so an integration can show where an answer or proposed action came from. 
Fail-closed release policy The deployed service starts from an explicit operation allow-list. An empty allow-list exposes no tools; an unknown or prohibited name prevents startup. A grant then narrows the released set further through scopes and privacy authority.

## Access and environments

Source: https://developers.allfullness.com/access

Know what is public, what requires registration and how controlled-beta access is activated.

Public without credentials OAuth authorization-server metadata OAuth protected-resource metadata OpenAPI 3.1 document A2A Agent Card 
Requires a registered OAuth client OAuth authorization, token exchange, Agent Action API, MCP and A2A execution require a client registered by Fullness with exact HTTPS redirect URIs and reviewed scopes. 
Requires an approved B2B partner Credit, Credit Products and Financial Passport routes use a separate partner API key. They additionally require an enabled environment, accepted DPA, allowed jurisdiction, contracted purpose and the private-beta feature flag. Start with partner access . 
Requires a signed-in Fullness workspace owner Grant management, webhook endpoint management and sandbox provisioning are management operations. They use the authenticated Fullness application boundary and a selected workspace; an external OAuth access token is not a management credential. 
Production may intentionally expose zero tools The live OpenAPI operation list is authoritative. Controlled-beta documentation does not override the production release gate. 
Request access Send the integration name, company, use case, required data, requested tools, callback URLs, intended environments and a security contact. Request developer access

## Products and availability

Source: https://developers.allfullness.com/products

Choose the implemented Fullness developer surface that matches your integration and access model.

Product map Product Use it for Authentication Availability Agent Platform Finance reads and approval-bound actions over HTTP, MCP and A2A OAuth 2.0 authorization code + PKCE Controlled public beta; live release allow-list applies Credit API Signed score attestations, batch scoring and health signals Partner API key; HMAC on mutating requests Private beta; partner, feature flag and compliance gates apply Financial Passport Holder-consent requests and cryptographic presentation verification Partner API key; HMAC on mutating requests Private beta; identity-service verification must be available Credit products Product discovery, eligibility, applications and approved lending lanes Partner API key; HMAC on mutating requests Private beta; jurisdiction, purpose and product configuration apply Verifier SDK Offline verification of Fullness credentials and Passport presentations Issuer keys, schemas and status material Preview source packages for TypeScript and Python 
Two separate credentials by design OAuth access tokens authorize Agent Platform requests. Credit and Passport API keys authorize approved B2B partner requests. Neither credential can be substituted for the other. 
What is not promised A route existing in source does not mean every partner or production environment can use it. The portal labels private-beta and release gates directly; onboarding confirms the base URL, key environment, purposes, jurisdictions and enabled products for your account.

## Credit and Passport access

Source: https://developers.allfullness.com/partner-access

Apply for an approved partner, receive a sandbox key and activate only the contracted data uses.

Private beta The partner service and onboarding route are implemented, but approval and API-key issuance remain operator controlled. A submitted application cannot call partner endpoints until it is approved. 
POST /api/credit-api/v1/partners/apply Submit a public partner application; no API key is required. 
Onboarding sequence Submit your company, use case and jurisdiction. Fullness reviews the application and data-processing requirements. An operator approves the partner and mints a sandbox key. Store the one-time prefix.secret value in server-side secret storage. Test the contracted purposes and jurisdictions in sandbox. Production access is enabled separately. 
Submit an application Use the credit API base URL supplied for the target environment. Shell Copy 
```
curl --request POST \
"$FULLNESS_CREDIT_API_BASE/api/credit-api/v1/partners/apply" \
--header 'content-type: application/json' \
--data '{
"name":"Example Lending",
"email":"security@example.com",
"company":"Example Lending Ltd",
"use_case":"Consent-based affordability verification",
"jurisdiction":"KE"
}'
```
Access checklist Approved partner status Sandbox or production enabled on the partner and key Current DPA accepted Requested jurisdiction on the allow-list X-Data-Use-Purpose matches a contracted purpose ff_tier0_credit_api_b2b enabled in the environment

## Credit and Passport quickstart

Source: https://developers.allfullness.com/credit-quickstart

Sign and send a real private-beta partner request without depending on an unpublished package.

Before you start You need the environment base URL and a full sandbox API key issued to an approved partner. The key is shown once and has prefix.secret form. 
1. Keep credentials server-side Environment Copy 
```
FULLNESS_CREDIT_API_BASE=https://sandbox-host-issued-during-onboarding
FULLNESS_CREDIT_API_KEY=prefix.secret
```
2. Sign the exact body Node.js Copy 
```
import { createHmac } from 'node:crypto';
const baseUrl = process.env.FULLNESS_CREDIT_API_BASE;
const apiKey = process.env.FULLNESS_CREDIT_API_KEY;
const secret = apiKey.slice(apiKey.indexOf('.') + 1);
const body = JSON.stringify({
did: 'did:fullness:subject-issued-by-fullness',
consent_token: 'consent-token-issued-for-this-release',
});
const signature = 'sha256=' + createHmac('sha256', secret)
.update(body, 'utf8')
.digest('hex');
```
3. Send a score request Node.js Copy 
```
const response = await fetch(
baseUrl + '/api/credit-api/v1/score',
{
method: 'POST',
headers: {
'content-type': 'application/json',
'x-api-key': apiKey,
'x-signature': signature,
'x-data-use-purpose': 'credit_scoring',
},
body,
},
);
const payload = await response.json();
if (!response.ok) throw new Error(payload.error?.code || 'CREDIT_API_ERROR');
console.log(payload.attestation);
```
4. Continue with the product you need Credit scores Financial Passport Credit products

## Partner authentication

Source: https://developers.allfullness.com/credit-authentication

Authenticate Credit and Financial Passport calls with an API key, exact-body HMAC and contracted purpose.

Headers Header When Value X-API-Key Every partner endpoint The full one-time prefix.secret key X-Signature POST, PUT, PATCH and DELETE sha256=<hex HMAC-SHA-256> over the exact raw body X-Data-Use-Purpose Endpoints that release personal or financial data A purpose approved for the partner 
GET requests are not signed The implemented middleware and TypeScript SDK require the API key on GET requests but do not require an HMAC signature. Mutating requests without a signature fail with MISSING_SIGNATURE . 
Exact-body rule Compute the HMAC from the same UTF-8 bytes sent on the wire. Do not parse and reserialize JSON between signing and sending. Extract the secret as everything after the first dot in the API key. Algorithm Copy 
```
signature = "sha256=" + hex(
HMAC_SHA256(api_key_secret, exact_raw_request_body)
)
```
Compliance gates Authentication proves which partner made the call. Data release additionally checks partner approval, beta status, key environment, DPA acceptance, jurisdiction and purpose. Treat a 403 as a policy decision; do not retry it as a transient error. 
Rate limits The service uses a token bucket per API key. The current default is 60 requests per minute with a burst of 120; configured premium limits may differ. On HTTP 429, honor Retry-After .

## Credit API

Source: https://developers.allfullness.com/credit-api

Request signed financial-health attestations and consented score signals through the implemented B2B service.

Private beta These endpoints are implemented behind ff_tier0_credit_api_b2b . They require an approved, beta-enabled partner and the environment-specific base URL issued during onboarding. 
POST /api/credit-api/v1/score Return one signed financial-health credential for a DID and consent token. 
POST /api/credit-api/v1/score/batch Return up to 100 per-DID attestations or inline errors. 
GET /api/credit-api/v1/health-signals/{did} Return premium per-dimension signals behind the composite score. 
POST /api/credit-api/v1/webhooks/score-changed Register a partner score-change webhook. 
TypeScript client The repository package @fullness/credit-api-sdk handles API-key headers, exact-body HMAC and purpose headers. It is supplied to approved integrators; public registry availability is not assumed. TypeScript Copy 
```
import { CreditApiClient } from '@fullness/credit-api-sdk';
const credit = new CreditApiClient({
baseUrl: process.env.FULLNESS_CREDIT_API_BASE,
apiKey: process.env.FULLNESS_CREDIT_API_KEY,
defaultPurpose: 'credit_scoring',
});
const result = await credit.getScore({
did: 'did:fullness:subject-issued-by-fullness',
consent_token: 'consent-token-issued-for-this-release',
});
console.log(result.attestation, result.consent_token_hash);
```
Score response The response contains a signed W3C credential and the SHA-256 hash of the supplied consent token for audit correlation. Do not treat a score response as permission to originate credit, move funds or bypass your own regulatory decisioning. 
Health signals The premium endpoint returns the DID, score, scoring window, dimensions, computation hash and computation timestamp. Availability and billable units are partner-tier dependent.

## Financial Passport

Source: https://developers.allfullness.com/financial-passport

Create holder-consent verification requests and verify signed threshold-based Financial Passport presentations.

Implemented private beta The four partner routes, identity-service gateway, cryptographic claim verification and tests exist. Verification fails closed with HTTP 503 when identity-service verification material is unavailable. 
POST /api/credit-api/v1/passport/request Create a verifier request and receive token, holder share URL, status URL and expiry. 
GET /api/credit-api/v1/passport/requests/{token}/status Poll pending, consented, fulfilled, rejected, expired or revoked state. 
POST /api/credit-api/v1/passport/verify Verify a VP JWT directly or resolve a fulfilled request token. 
POST /api/credit-api/v1/passport/batch Verify up to 50 VP JWTs or request tokens with per-item results. 
Request criteria A request must contain at least one supported criterion. The holder sees the verifier name, human-readable purpose and requested thresholds before deciding whether to fulfil it. JSON Copy 
```
{
"purpose": "affordability_assessment",
"purpose_description": "Confirm rental affordability",
"verifier_name": "Example Property",
"criteria": {
"income": {
"currency_code": "KES",
"monthly_amount": 50000,
"months_required": 12,
"source_rail": "mpesa",
"source_country": "KE"
},
"score": { "min": 65 },
"dti": { "max": 0.4 },
"savings_rate": { "min": 0.1 }
},
"ttl_seconds": 86400
}
```
End-to-end flow Create the request. Send share_url to the holder; do not imitate the consent screen. Poll status_url with bounded backoff. When presentation_available is true, call verify with request_token . Require valid === true before trusting any returned claim. Evaluate overall_holds separately as the business outcome. 
Current SDK path Version 0.1.0 of @fullness/credit-api-sdk does not yet expose Passport-specific convenience methods. Its public low-level request method still applies the API key, exact-body HMAC and purpose header, so approved integrators can call the implemented routes now. TypeScript Copy 
```
const request = await credit.request<{
token: string;
share_url: string | null;
}>(
'POST',
'/api/credit-api/v1/passport/request',
{
purpose: 'affordability_assessment',
purpose_description: 'Confirm rental affordability',
criteria: {
income: { currency_code: 'KES', monthly_amount: 50000, months_required: 12 },
},
},
{ purpose: 'affordability_assessment' },
);
// Give request.share_url to the holder, then poll request.status_url.
const verified = await credit.request<{
valid: boolean;
overall_holds: boolean;
}>(
'POST',
'/api/credit-api/v1/passport/verify',
{ purpose: 'affordability_assessment', request_token: request.token },
{ purpose: 'affordability_assessment' },
);
```
Validity is not approval valid means the presentation and embedded credentials passed verification and holder binding. overall_holds is the AND of disclosed threshold checks. Neither value authorizes a loan, payment or account action.

## Credit products

Source: https://developers.allfullness.com/credit-products

Integrate the implemented partner façade for product discovery, eligibility, applications and configured credit lanes.

Configuration-dependent private beta The routes and SDK helpers exist, but a usable response depends on partner approval, feature flag, tenant/workspace, DID resolution, jurisdiction, purpose and configured products. Disbursement and specialist lanes are not implied to be enabled for every partner. 
Core flow GET /api/credit-api/v1/credit-products List active products for a tenant and workspace. GET /api/credit-api/v1/credit-products/offers List pre-qualified offers for a subject DID. GET /api/credit-api/v1/credit-products/eligibility Check eligibility for a product and amount. POST /api/credit-api/v1/credit-products/apply Submit a loan application. GET /api/credit-api/v1/credit-products/applications/{applicationId} Read application status. POST /api/credit-api/v1/credit-products/applications/{applicationId}/disburse Disburse an approved application when the partner lane permits it. 
Additional implemented lanes Facility repayment schedule / statement Marketplace offer listing, application and acceptance BNPL checkout creation Merchant cash advance status Working-capital facility status The partner API reference summarizes the implemented route families. Approved integrators receive the applicable schema contract during onboarding. 
Typed eligibility example TypeScript Copy 
```
const { data: eligibility, correlation_id } =
await credit.checkCreditProductEligibility({
tenant_id: 'tenant-uuid',
workspace_id: 'workspace-uuid',
did: 'did:fullness:subject-issued-by-fullness',
product_type: 'bnpl',
amount: 5000,
});
console.log(eligibility.allowed, eligibility.reasons, correlation_id);
```
Operational rules Pass tenant, workspace and DID exactly as assigned. Preserve correlation_id for support and audit. Use a stable idempotency_key for application and disbursement retries. Do not infer approval from product listing or eligibility alone. Honor the returned status and next steps.

## Credential verification

Source: https://developers.allfullness.com/credential-verification

Verify Fullness credentials and Financial Passport presentations in TypeScript or Python without trusting unverified claims.

Preview source packages The repository contains @fullness/verifier-sdk 0.1.0-preview.0 and fullness-verifier 0.1.0-preview.0. They are described as source packages for approved integrators; this portal does not claim public registry availability. 
Supported Passport types FullnessIncomePassportCredential FullnessIncomeThresholdAttestation FullnessCompositeThresholdAttestation FullnessFinancialPassport presentation bundles 
TypeScript TypeScript Copy 
```
import { verifyFinancialPassport } from '@fullness/verifier-sdk';
const result = await verifyFinancialPassport(vpJwt, {
rejectContradictedChecks: true,
});
if (!result.valid) throw new Error(result.error?.message);
console.log(result.holder, result.checks, result.overall_holds);
```
Python Python Copy 
```
from fullness_verifier import verify_financial_passport
result = verify_financial_passport(vp_jwt)
if not result["valid"]:
raise ValueError(result["error"]["message"])
print(result["holder"], result["checks"], result["overall_holds"])
```
Verification rules Verify every embedded credential signature against issuer material. Validate schema, expiry and revocation. Bind every credential subject to the presentation holder. Recompute disclosed threshold signals when comparable values are present. Keep cryptographic validity separate from the business threshold outcome.

## Credit and Passport API reference

Source: https://developers.allfullness.com/credit-reference

Review the implemented partner-facing Credit and Financial Passport route families without exposing internal service operations.

Partner-scoped contract distribution The service OpenAPI also contains internal administration and consumer-only operations, so it is not exported wholesale from this public portal. Approved integrators receive the applicable partner contract and base URL during onboarding. 
Partner route families Public partner application Partner profile, usage and webhook self-service Credit score attestations and health signals Financial Passport request, status, verification and batch verification Score-change webhooks Credit product discovery, eligibility, applications and configured lanes 
Machine-readable contracts The Agent Platform has a public, live and release-filtered OpenAPI 3.1 reference . Credit and Passport client schemas remain private-beta onboarding material until a public partner-only contract is separated from the broader service definition.

## Agent OAuth and scopes

Source: https://developers.allfullness.com/authentication

Implement authorization code with PKCE S256, workspace consent, token exchange and revocation.

GET /.well-known/oauth-authorization-server Live authorization, token, revocation, PKCE and supported-scope metadata. 
GET /.well-known/oauth-protected-resource Resource metadata for OAuth-aware MCP and API clients. 
GET /oauth/authorize Validate the request and redirect the user to the Fullness consent screen. 
POST /oauth/token Exchange a single-use authorization code and PKCE verifier for an access token. 
POST /oauth/revoke Immediately revoke an access token. 
Authorization request requirements Parameter Requirement client_id Active registered client redirect_uri Exact registered HTTPS URI response_type code code_challenge_method S256 code_challenge Derived from the server-held verifier scope Non-empty, registered and currently released purpose Human-readable, 3–240 characters state Unpredictable, 16–512 characters 
Token behavior Authorization codes expire after five minutes and are single-use. Access tokens are opaque and expire after one hour. Revoking the token, grant or client takes effect immediately. Confidential clients may use client_secret_post ; public clients use no token-endpoint authentication and still require PKCE. 
Scope composition A usable grant combines an action scope, data authority and required privacy scopes. Exact tool:<name> scopes are supported, but never bypass privacy requirements or the prohibited-tool boundary. 
Example scope set Copy 
```
actions:read
tool:get_account_balances
privacy:shareAccounts
```
A token is not an approval OAuth delegates authority to request an operation. Consequential actions still go through Fullness policy and an independent Fullness-hosted approval decision.

## Agent API reference

Source: https://developers.allfullness.com/api-reference

Browse the operations currently published by the live Fullness OpenAPI 3.1 contract.

Generated from the deployed release This page loads the production OpenAPI document. It does not maintain a separate endpoint list, so unreleased operations cannot drift into the reference. 
Loading the live OpenAPI contract… 
JavaScript is disabled. Open the raw OpenAPI 3.1 document . 
Stable discovery URLs 
GET /openapi.json OpenAPI 3.1 operations filtered by the deployed release allow-list. 
GET /.well-known/agent-card.json A2A Agent Card generated from the same released operations. 
Download the current OpenAPI JSON →

## Agent Action API

Source: https://developers.allfullness.com/actions

Execute governed tools, track durable status and hand approval decisions back to Fullness.

POST /external/v1/actions/{toolName}/execute Execute a tool released to the environment and authorized for the grant. 
GET /external/v1/actions/{actionId} Read status for an action owned by the same grant and workspace. 
Request body JSON Copy 
```
{
"arguments": {
"period": "last_30_days"
},
"idempotencyKey": "order-import-2026-09-01-0001"
}
```
idempotencyKey is required for every non-read operation and must contain 16–200 characters. Do not reuse a key for different arguments. 
Action states queued waiting_approval waiting_retry running succeeded failed cancelled Treat waiting_approval as durable progress, not an error. Present approvalUrl to the user, retain action.id , and poll the status endpoint with bounded backoff. 
Approval boundary Do not include an approval property; the API rejects it. Do not embed, proxy or imitate the Fullness approval experience. Do not collect the user’s Fullness password or approval credentials. Do preserve the returned activity and approval URLs. 
Retry policy Reads may be retried with bounded exponential backoff after transient failures. The official SDKs never retry writes automatically. For a non-read operation, reuse the original idempotency key only when retrying the same intended operation.

## MCP

Source: https://developers.allfullness.com/mcp

Connect an OAuth-authorized MCP client to Fullness’s released, scope-filtered finance tools.

POST /external/mcp JSON-RPC MCP endpoint protected by the same OAuth grant as the HTTP API. 
Connection values MCP configuration Copy 
```
Server URL: https://api.allfullness.com/api/agent/external/mcp
OAuth metadata: https://api.allfullness.com/api/agent/.well-known/oauth-protected-resource
Transport: HTTP JSON-RPC
```
Implemented MCP methods Method Behavior initialize Negotiates protocol version 2025-06-18 . ping Connectivity check. tools/list Returns only tools released and authorized for the grant. tools/call Executes through the governed action kernel. resources/list Lists the connected-capabilities resource. resources/read Reads fullness://capabilities . 
Calling non-read tools Supply the required idempotency key inside the reserved _fullness object. Approval fields are forbidden. JSON Copy 
```
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "a_released_non_read_tool",
"arguments": {
"_fullness": {
"idempotencyKey": "your-stable-key-at-least-16-chars"
}
}
}
}
```
Client listings are separate from protocol access ChatGPT packaging and marketplace submission require Fullness-managed registration and review. The MCP URL alone does not create a registered OAuth client or release additional tools.

## A2A

Source: https://developers.allfullness.com/a2a

Use Fullness’s Agent Card and JSON-RPC task methods without bypassing scopes or approvals.

GET /.well-known/agent-card.json Published Agent Card with only the currently released skills. 
POST /external/a2a OAuth-protected JSON-RPC endpoint for A2A tasks. 
Implemented methods message/send starts a released skill with JSON input. tasks/get reads a task belonging to the same grant. 
Send a message JSON Copy 
```
{
"jsonrpc": "2.0",
"id": "request-1",
"method": "message/send",
"params": {
"skillId": "get_spending_summary",
"input": {
"period": "last_30_days"
}
}
}
```
For a released non-read skill, add input._fullness.idempotencyKey . Never add an approval value. 
Task mapping Fullness maps a waiting approval to A2A input-required , a successful result to completed , and an unsuccessful execution to failed . Artifacts retain both the Fullness result and action object. 
Current capability declaration The Agent Card declares no streaming and no push notifications. State-transition history is supported.

## Webhooks

Source: https://developers.allfullness.com/webhooks

Register workspace event endpoints and verify Fullness signatures against the unmodified request body.

Management operation Webhook registration is performed by an authenticated Fullness workspace owner or by Fullness during controlled-beta onboarding. External OAuth access tokens are not webhook-management credentials. 
GET /v1/external/webhooks List endpoints for the selected authenticated Fullness workspace. 
POST /v1/external/webhooks Register an HTTPS URL and one or more event types; the signing secret is returned once. 
POST /v1/external/webhooks/{endpointId}/revoke Stop future delivery to an endpoint. 
Delivery headers fullness-event-id — unique delivery/event identifier fullness-timestamp — Unix timestamp in seconds fullness-signature — v1=<hex HMAC> 
Signature construction Algorithm Copy 
```
signedPayload = timestamp + "." + eventId + "." + rawRequestBody
expected = "v1=" + hex(HMAC_SHA256(signingSecret, signedPayload))
```
Compare signatures in constant time. Reject timestamps more than five minutes from the receiver’s clock and persist accepted event IDs so replays are rejected. 
Node.js verification Node.js Copy 
```
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verifyFullnessWebhook({ rawBody, secret, timestamp, eventId, signature }) {
const age = Math.abs(Date.now() / 1000 - Number(timestamp));
if (!Number.isFinite(age) || age > 300) return false;
const expected = 'v1=' + createHmac('sha256', secret)
.update(`${timestamp}.${eventId}.${rawBody}`)
.digest('hex');
const left = Buffer.from(expected);
const right = Buffer.from(signature);
return left.length === right.length && timingSafeEqual(left, right);
}
```
Delivery behavior Fullness sends JSON with a 10-second timeout and does not follow redirects. HTTP 408, 429 and 5xx responses are retryable; other non-success responses fail the delivery. Receivers must still be idempotent because retries can repeat an event.

## SDKs

Source: https://developers.allfullness.com/sdks

Use the repository TypeScript and Python clients, or call the canonical HTTP API directly.

Distribution status The TypeScript and Python SDKs exist in the Fullness platform repository at version 0.1.0. They are supplied to approved integrators during the controlled beta; this page does not claim that either package is available in a public registry. 
TypeScript beta compatibility The 0.1.0 TypeScript status union does not yet include the runtime’s waiting_retry value. Until the next SDK patch, treat response status as forward-compatible data or use raw HTTP when handling retry state. 
TypeScript Package source: packages/agent-api-sdk . Node.js 20 or newer. TypeScript Copy 
```
import { FullnessClient } from '@fullness/agent-api';
const fullness = new FullnessClient({
accessToken: process.env.FULLNESS_ACCESS_TOKEN,
});
const action = await fullness.execute(
'get_spending_summary',
{ period: 'last_30_days' },
);
console.log(action.result, action.action.activityUrl);
```
Python Package source: sdks/python/fullness-agent . Python 3.10 or newer; zero runtime dependencies. Python Copy 
```
from fullness_agent import FullnessClient
client = FullnessClient(access_token=os.environ["FULLNESS_ACCESS_TOKEN"])
action = client.execute(
"get_spending_summary",
{"period": "last_30_days"},
)
print(action["result"])
```
SDK safety behavior Neither SDK approves an action. Neither SDK retries a write automatically. The caller owns stable idempotency-key generation. API errors preserve HTTP status, Fullness error code and response payload. The TypeScript SDK can verify webhooks against the raw body. 
Raw HTTP is always canonical The OpenAPI document and OAuth metadata are the source of truth. If an SDK version lags the live contract, use the versioned HTTP routes and report the mismatch.

## Sandbox and testing

Source: https://developers.allfullness.com/sandbox

Test released workflows without treating research tooling as authorization for real money movement.

Provisioning Sandbox creation is an authenticated Fullness management operation and is currently provisioned during controlled-beta onboarding. A sandbox does not widen an OAuth client’s scopes or release additional tools. 
Recommended integration tests OAuth state mismatch is rejected. PKCE verifier mismatch is rejected. Expired, revoked and cross-workspace grants fail. An unreleased tool is absent from discovery and cannot execute. A non-read retry reuses the same idempotency key and arguments. Caller-supplied approval data is rejected. Webhook stale timestamps and repeated event IDs are rejected. Approval and activity links return the user to Fullness. 
Payment research is not payment execution The external payment-proof route evaluates synthetic ACP/AP2-shaped mandates. Its persistence layer forces production_enabled = false . It does not move, hold, settle or authorize money.

## Errors and retries

Source: https://developers.allfullness.com/errors

Handle authentication, scope, validation, idempotency and transient failures without unsafe retries.

Error envelope JSON Copy 
```
{
"error": {
"code": "INSUFFICIENT_SCOPE"
}
}
```
OAuth protocol errors use the standard top-level error and error_description fields. Action and management routes use the structured envelope above. 
HTTP handling Status Meaning Client behavior 202 Approval or asynchronous completion required Persist action ID; follow handoff and poll. 400 Invalid input, forbidden request shape, or beta idempotency-reuse response Correct the request; do not retry unchanged. 401 Missing, expired or revoked token Reauthorize through the supported flow. 403 Scope or Fullness policy denial Do not retry; request only justified authority. 404 Action not found in this grant/workspace Verify identifier and tenant context. 409 Contracted idempotency conflict response Do not change intent under the same key. 429 Throttled Use bounded backoff and response metadata. 5xx Transient service failure Retry reads; retry writes only with the original key and intent. During the controlled beta, handle both HTTP 400 with IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_REQUEST and HTTP 409 as terminal idempotency conflicts. This preserves compatibility while the runtime is aligned to its OpenAPI 409 response. 
Correlation and evidence Retain the response correlation ID, action ID and activity URL in operational logs. Do not log access tokens, authorization codes, PKCE verifiers, webhook secrets or financial payloads unnecessarily. 
Numeric limits are negotiated Rate limits can vary by plan, tenant and release cohort. Do not hard-code an unpublished global number.

## Security and approvals

Source: https://developers.allfullness.com/security

Apply the Fullness trust boundary correctly and know where deeper assurance information lives.

Integration responsibilities Store tokens and client secrets only in server-side secret storage. Use exact HTTPS redirect URIs and validate OAuth state. Request the smallest practical scope set. Keep tenant/workspace context explicit. Verify webhooks before parsing their JSON. Preserve evidence and approval handoffs. Support immediate disconnection and revocation. 
Fullness responsibilities Fullness enforces release gates, grant and workspace binding, policy, approvals, evidence, idempotency, revocation and prohibited-tool boundaries inside the execution path shared by API and agent protocols. 
Trust and service health Security, privacy, compliance and assurance material belongs in the Fullness Trust Center . Live availability and incidents belong on the status page . 
Report a security issue Do not include credentials or sensitive financial data in an ordinary documentation email. Use the responsible-disclosure contact published by the Trust Center.

## Changelog

Source: https://developers.allfullness.com/changelog

Track public developer-contract and documentation changes.

September 1, 2026 Developer portal 0.3 Added verified private-beta Credit API, Credit Products and Financial Passport guides. Added a partner-scoped route reference while keeping internal service operations out of the public portal. Documented the current low-level Credit SDK request path for Passport calls and the missing convenience-method compatibility gap. Corrected partner authentication guidance: GET requests require the API key but are not HMAC-signed. Kept OAuth and partner API keys as explicit, separate trust boundaries. 
September 1, 2026 Developer portal 0.2 Added real multi-page quickstarts for OAuth, actions, MCP, A2A and webhooks. Added a live OpenAPI operation browser driven by the deployed release contract. Added searchable documentation, sitemap and llms.txt . Clarified controlled-beta registration, SDK distribution and management-operation boundaries. Aligned action lifecycle and error documentation with runtime contracts. 
August 31, 2026 Controlled public-beta guide Published the canonical overview for OpenAPI, OAuth, Agent Action API, SDKs, webhooks, MCP, A2A, approval states and release boundaries. 
Machine-readable changelog →