Voice

The Voice surface is a commercial surface in the Identities AI app.

Canonical protocol references:

• README
• SPEC.md
• SDK matrix

Ratify v1 does not define a separate voice:* scope family. Voice is modeled with the canonical meeting and communication scopes, plus ordinary data or tool scopes when the agent does more than speak.

What Voice is for

Use the Voice surface when you need to authorize:

• outbound sales or support calls
• voice intake and identity verification
• live assistant speaking on a call
• call-center or telephony agent actions
• speech plus downstream app actions during the same session

How to think about it

Voice is not just “can the model speak”.

The important questions are:

1. Is this voice agent authorized to represent the person or organization?
2. Is it allowed to speak in this session?
3. Is it allowed to perform follow-up actions after speaking, such as creating a record or sending a message?

That usually maps to:

• meeting:attend for joining or participating in a live session
• meeting:speak for speaking permission
• comms:message:send for voice-driven outbound messaging workflows
• execute:tool for tool actions triggered by a voice session
• data:write for CRM or case creation

Voice flow

sequenceDiagram
  autonumber
  participant Org as Customer Org
  participant Platform as Voice Platform
  participant Ratify as Ratify Platform
  participant Agent as Voice Agent
  participant Call as Call / Meeting Surface

  Org->>Platform: Enable voice integration
  Platform->>Ratify: Register Voice surface + callback URL
  Ratify-->>Platform: API key, signing secret, webhook secret
  Org->>Platform: Approve voice policy
  Platform->>Agent: Load delegated identity
  Call->>Ratify: Request proof / challenge
  Ratify->>Agent: Challenge
  Agent->>Agent: Sign with SDK
  Agent-->>Call: Proof bundle
  Call->>Call: Verify proof and scope
  Ratify-->>Platform: Callback for lifecycle or revocation

SDK examples

The example below treats a live voice agent as a speaking participant. If the session also performs app actions, add the required action scope alongside the voice scope.

Go

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

TypeScript

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

Python

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

Rust

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

Registration

1. Register the platform in the Identities AI app.
2. Choose the Voice surface.
3. Configure your callback URL.
4. Store the API key and webhook secret.
5. Connect the voice runtime to the proof bundle flow.

What your app must do

Your voice platform usually owns:

• the telephony provider or media stack
• session establishment
• turn-taking and transcript state
• the SDK call that signs or verifies the proof bundle
• the callback endpoint for lifecycle state

Ratify owns the managed registration, policy, audit, revocation, and enforcement surface.

If the voice session also writes to CRM, sends email, or calls tools, those actions need their own scopes in addition to the speaking scope.