Agent Platform Integration

This is the page to read if you are building a meeting-note platform, a finance-agent platform, a generic MCP/A2A platform, or a physical AI platform.

Ratify gives you two things:

• a free, open protocol and SDK layer for proof objects
• a commercial surface for customer onboarding, policy, audit, callbacks, and managed enforcement

Canonical protocol sources:

• README
• SPEC.md
• SDK matrix

The managed product lives in the Identities AI app.

What the platform developer owns

Your platform owns:

• the user experience
• agent runtime
• customer workspace setup
• local caching and session state
• UX for delegations, consent, and revocation
• application-specific business logic

What Ratify owns

Ratify owns:

• the proof format
• the verifier semantics
• the SDK implementations
• the hosted control plane
• the callback delivery layer
• managed surfaces such as API Gateway, Meetings, Voice, and Physical AI

Concrete integration patterns

Platform type	What the customer wants	Ratify surface	What your runtime does
Meeting note taker	”Only approved agents may join our Zoom/Teams/Meet calls.”	Meetings	Present a proof for meeting:attend and respond to challenges
Voice platform	”Only approved voice agents may speak in a live call.”	Voice	Present a proof for meeting:speak and respond to turn-taking challenges
Finance agent	”Only approved agents may call payments or ledger routes.”	API Gateway	Present a proof for payments:send, data:read, or execute:tool
Generic MCP / A2A platform	”Only approved tools or peers may be invoked.”	API Gateway	Verify proof bundles before tool dispatch or agent-to-agent routing
Physical AI platform	”Only approved devices may actuate or move.”	Physical AI	Verify proof bundles on-device before actuation or motion

Registration flow

1. Sign in to the Identities AI app.
2. Decide whether you are starting with a personal account or an organization.
3. Personal accounts can register one draft API Gateway platform.
4. If you need publishing, meetings, voice, physical AI, or multiple platforms, create an organization.
5. For organizations, verify the publisher domain if you want publishing.
6. Register a platform in the Developer Console.
7. Choose the surface type: API Gateway, Meetings, Voice, or Physical AI.
8. Ratify issues an API key, a signing secret, and a webhook secret.
9. Your platform stores those credentials in its own control plane.
10. Your customer admins connect their workspace to your platform.

End-to-end flow

sequenceDiagram
  autonumber
  participant Customer as Customer Org Admin
  participant Platform as Your Agent Platform
  participant Ratify as Ratify Platform
  participant Agent as Agent Runtime
  participant Surface as Protected Surface

  Customer->>Platform: Enable integration
  Platform->>Ratify: Register platform + callback URL
  Ratify-->>Platform: API key, signing secret, webhook secret
  Customer->>Platform: Approve agent usage in workspace
  Platform->>Agent: Create or load delegated identity
  Surface->>Ratify: Request challenge or verification
  Ratify->>Agent: Challenge / verification request
  Agent->>Agent: Sign with Ratify SDK
  Agent-->>Surface: Proof bundle
  Surface->>Surface: Verify bundle or forward to Ratify-managed enforcement
  Ratify-->>Platform: Callback event for lifecycle or approval

Who challenges whom

The verifier challenges the agent.

In practice:

• the meeting surface, gateway, or device issues a fresh challenge
• the agent runtime signs that challenge with the SDK
• the proof bundle is returned to the verifier
• the verifier checks scope, expiry, revocation, constraints, and freshness

The platform does not challenge Ratify. The agent proves itself to Ratify.

SDK verification examples

The SDK call pattern is the same across languages. Only the language syntax changes.

Meeting scope

Go

result := ratify.Verify(bundle, ratify.VerifyOptions{
  RequiredScope: ratify.ScopeMeetingAttend,
})
if !result.Valid {
  http.Error(w, result.ErrorReason, http.StatusForbidden)
  return
}

TypeScript

const result = await verifyBundle(bundle, {
  required_scope: SCOPE_MEETING_ATTEND,
});
if (!result.valid) {
  throw new Error(result.error_reason);
}

Python

result = verify_bundle(bundle, VerifyOptions(required_scope=SCOPE_MEETING_ATTEND))
if not result.valid:
    raise RuntimeError(result.error_reason)

Rust

let result = verify_bundle(
    &bundle,
    &VerifyOptions {
        required_scope: SCOPE_MEETING_ATTEND.into(),
        ..Default::default()
    },
);
assert!(result.valid, "{}", result.error_reason);

Finance / API Gateway scope

Go

result := ratify.Verify(bundle, ratify.VerifyOptions{
  RequiredScope: ratify.ScopePaymentsSend,
})
if !result.Valid {
  http.Error(w, result.ErrorReason, http.StatusForbidden)
  return
}

TypeScript

const result = await verifyBundle(bundle, {
  required_scope: SCOPE_PAYMENTS_SEND,
});
if (!result.valid) {
  return new Response(result.error_reason, { status: 403 });
}

Python

result = verify_bundle(bundle, VerifyOptions(required_scope=SCOPE_PAYMENTS_SEND))
if not result.valid:
    raise PermissionError(result.error_reason)

Rust

let result = verify_bundle(
    &bundle,
    &VerifyOptions {
        required_scope: SCOPE_PAYMENTS_SEND.into(),
        ..Default::default()
    },
);
assert!(result.valid, "{}", result.error_reason);

Physical AI scope

Go

result := ratify.Verify(bundle, ratify.VerifyOptions{
  RequiredScope: ratify.ScopeRobotOperate,
})
if !result.Valid {
  return fmt.Errorf("deny actuation: %s", result.ErrorReason)
}

TypeScript

const result = await verifyBundle(bundle, {
  required_scope: SCOPE_ROBOT_OPERATE,
});
if (!result.valid) {
  throw new Error(result.error_reason);
}

Python

result = verify_bundle(bundle, VerifyOptions(required_scope=SCOPE_ROBOT_OPERATE))
if not result.valid:
    raise PermissionError(result.error_reason)

Rust

let result = verify_bundle(
    &bundle,
    &VerifyOptions {
        required_scope: SCOPE_ROBOT_OPERATE.into(),
        ..Default::default()
    },
);
assert!(result.valid, "{}", result.error_reason);

The callback contract

Your platform also needs an HTTPS callback endpoint.

Ratify uses the callback URL for asynchronous state changes, not for proof verification itself. The endpoint receives:

• connection.created
• connection.key_rotated
• connection.removed
• delegation.approved
• delegation.denied
• delegation.revoked

For exact event payloads and signature rules, see Callbacks and Webhooks.

What the callback endpoint must do

Your callback implementation should:

• verify X-Ratify-Signature
• verify X-Ratify-Timestamp
• reject stale requests
• deduplicate with X-Ratify-Delivery-ID
• respond with a 2xx status to acknowledge success
• return a non-2xx status if you want Ratify to retry

Use the callback for state updates:

• store connection metadata
• update caches after key rotation
• mark delegations approved or denied
• invalidate permissions after revocation
• deactivate a removed connection

Simple mental model

If you are building a platform, the split is:

• your product owns the agent runtime and customer UX
• Ratify owns the cryptographic proof model
• Ratify’s commercial surface owns customer onboarding, policy, audit, callbacks, and managed enforcement
• the SDKs are the bridge between your runtime and the verifier