API · Manage · Authorizations
Approve the authorization.
Sign off on a pending human-in-the-loop checkpoint that an agent's cascade is paused against. Authorizations are the human-attestation primitive — every high-stakes mutation that lands via an agent token is gated on one, so a board can audit which person signed off on which action and when.
The endpoint is typically called from Matter's hosted approval portal: the human follows a signature_url from an email or Slack notification, reviews the action context (what's being approved, by which agent, with what blast radius, citing which underlying resource), and clicks "Approve." For headless approval flows, supply the signature_token returned with the authorization to attest by API.
On approval, the dependent cascade resumes from the exact step it paused at — no replan, no drift. The action is recorded as taken by the human principal with the agent's identity attached as acting_on_behalf_of in the audit log.
Prerequisites - Authorization must be in pending status. Returns 409 authorization_already_resolved otherwise. - stakeholder_id (the approving human) must match the requested_of on the authorization; mismatched approvers receive 403 wrong_approver.
Idempotent via Idempotency-Key. See idempotency.
See also: Authentication overview, Authorizations API overview.
Last updated
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
stakeholder_idstringOptionalsignature_tokenstringOptionalResponse Body
application/json
application/problem+json
application/problem+json
application/problem+json
Request
curl -X POST "https://api.mattermode.com/v1/authorizations/{id}/approve" \ -H "Content-Type: application/json" \ -d '{ "stakeholder_id": "stk_7Hpx9WxY", "signature_token": "string" }'const body = JSON.stringify({ "stakeholder_id": "stk_7Hpx9WxY", "signature_token": "string"})fetch("https://api.mattermode.com/v1/authorizations/{id}/approve", { method: "POST", headers: { "Content-Type": "application/json" }, body})package mainimport ( "fmt" "net/http" "io/ioutil" "strings")func main() { url := "https://api.mattermode.com/v1/authorizations/{id}/approve" body := strings.NewReader(`{ "stakeholder_id": "stk_7Hpx9WxY", "signature_token": "string" }`) req, _ := http.NewRequest("POST", url, body) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body))}import requestsheaders = { "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc", "Matter-Version": "2026-06-10", "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b",}payload = { "stakeholder_id": "stk_7Hpx9WxY", "signature_token": "string"}resp = requests.post( "https://api.mattermode.com/v1/authorizations/id_placeholder/approve", headers=headers, json=payload,)resp.raise_for_status()print(resp.json())import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import java.net.http.HttpResponse.BodyHandlers;import java.time.Duration;import java.net.http.HttpRequest.BodyPublishers;var body = BodyPublishers.ofString("""{ "stakeholder_id": "stk_7Hpx9WxY", "signature_token": "string"}""");HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder() .uri(URI.create("https://api.mattermode.com/v1/authorizations/{id}/approve")) .header("Content-Type", "application/json") .POST(body) .build();try { HttpResponse<String> response = client.send(requestBuilder.build(), BodyHandlers.ofString()); System.out.println("Status code: " + response.statusCode()); System.out.println("Response body: " + response.body());} catch (Exception e) { e.printStackTrace();}using System;using System.Net.Http;using System.Text;var body = new StringContent("""{ "stakeholder_id": "stk_7Hpx9WxY", "signature_token": "string"}""", Encoding.UTF8, "application/json");var client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/authorizations/{id}/approve", body);var responseBody = await response.Content.ReadAsStringAsync();curl --request POST 'https://api.mattermode.com/v1/authorizations/id_placeholder/approve' \ --header 'Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc' \ --header 'Matter-Version: 2026-06-10' \ --header 'Idempotency-Key: ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b' \ --header 'Content-Type: application/json' \ --data '{ "stakeholder_id": "stk_7Hpx9WxY", "signature_token": "string"}'const response = await fetch("https://api.mattermode.com/v1/authorizations/id_placeholder/approve", { method: "POST", headers: { "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc", "Matter-Version": "2026-06-10", "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b", "Content-Type": "application/json", }, body: JSON.stringify({ "stakeholder_id": "stk_7Hpx9WxY", "signature_token": "string" }),});if (!response.ok) { throw new Error(`Matter API ${response.status}: ${await response.text()}`);}const data = await response.json();console.log(data);Response
application/json{
"id": "string",
"object": "authorization",
"token_id": "tok_4Kj2m8pQ",
"action": "string",
"payload_hash": "string",
"status": "pending",
"expires_at": 1745539200,
"signature_url": "https://your.app/webhooks/matter",
"approved_by_stakeholder_id": "string",
"approved_at": 0,
"denied_reason": "string",
"metadata": {},
"created": 1745539200,
"updated": 1745539200,
"livemode": false
}{
"type": "https://mattermode.com/docs/errors/invalid_request",
"title": "Invalid request",
"status": 400,
"code": "invalid_request",
"detail": "Request body could not be parsed as JSON.",
"doc_url": "https://mattermode.com/docs/guides/errors#invalid_request",
"request_id": "req_Qw9xYz8A"
}{
"type": "https://mattermode.com/docs/errors/authentication_required",
"title": "Authentication required",
"status": 401,
"code": "authentication_required",
"detail": "No bearer token was supplied. Pass `Authorization: Bearer sk_live_...` on every request.",
"doc_url": "https://mattermode.com/docs/guides/errors#authentication_required",
"request_id": "req_Qw9xYz8A"
}{
"type": "https://mattermode.com/docs/errors/rate_limit_exceeded",
"title": "Rate limit exceeded",
"status": 429,
"code": "rate_limit_exceeded",
"detail": "Request rate exceeded for this key. Retry after `retry_after` seconds or honor the `Retry-After` header.",
"doc_url": "https://mattermode.com/docs/guides/errors#rate_limit_exceeded",
"request_id": "req_Qw9xYz8A",
"retry_after": 30
}