Skip to Content

Request approval for an OAuth tool intent

Creates one immutable batch of up to 20 tool calls for one intent.

POST
/v1/approval-requests

Creates one immutable batch of up to 20 tool calls for one intent. Only an OAuth access token may create a request. The owner opens approvalUrl and decides in a signed-in owner session. Requests expire after 30 minutes; the original OAuth token must remain valid. Repeating idempotencyKey for the same caller returns the same request; different content conflicts. Credential-bearing arguments are refused.

Authorization

apiKey
headerx-api-key<token>

Request Body

application/json
  1. body
intent*string
Length1 <= length <= 500
calls*array<>
Items1 <= items <= 20
idempotencyKey*string
Length1 <= length <= 128

Response Body

ApprovalRequest

application/json
  1. response
id*ApprovalRequestId
Match^apr_[0-9a-hjkmnp-tv-z]{16,24}$
organizationId*OrganizationId
Match^org_[0-9a-hjkmnp-tv-z]{16,24}$
namespaceId*|null
clientId*string
requestedBy*UserId
Match^user_[0-9a-hjkmnp-tv-z]{16,24}$
intent*string
calls*array<>
Items1 <= items <= 20
status*string
Value in"pending""executing""executed""rejected""failed""expired"
expiresAt*string
createdAt*string
decidedAt*string|null
decidedBy*|null
reason*string|null
results*array<any>|null
error*string|null
approvalUrl*string
Example Request
import { createClient } from "samva";

const samva = createClient({ apiKey: process.env.SAMVA_API_KEY! });

const result = await samva.approvalRequests.create({
  "intent": "example",
  "calls": [
    {
      "toolName": "example",
      "arguments": {}
    }
  ],
  "idempotencyKey": "example"
});
Example Response
{
  "id": "string",
  "organizationId": "string",
  "namespaceId": "string",
  "clientId": "string",
  "requestedBy": "string",
  "intent": "string",
  "calls": [
    {
      "toolName": "string",
      "arguments": {
        "property1": "string",
        "property2": "string"
      }
    }
  ],
  "status": "pending",
  "expiresAt": "string",
  "createdAt": "string",
  "decidedAt": "string",
  "decidedBy": "string",
  "reason": "string",
  "results": [],
  "error": "string",
  "approvalUrl": "string"
}

Related documentation