API · Platform · Tokens
Revoke the token.
Permanently disable a scoped token. Use when an agent integration is decommissioned, when credentials may have leaked, or when a delegation's underlying human relationship ends (employee offboarding, vendor termination).
Revocation is forward-only and instantaneous — the token's hash is marked invalid in the auth path, and the next API call presenting it returns 401 token_revoked. Historical AuditEntry rows that reference the token are preserved unchanged so prior actions remain attributable for the SOC 2 trail.
Prerequisites - Token must not already be revoked or expired. Calling revoke on a terminal-state token returns 200 OK (idempotent no-op). - The caller must hold tokens.write scope on the same account, OR be acting as the human principal named on the token's delegation chain.
Returns 200 OK with the revoked token resource. Idempotent via Idempotency-Key. See idempotency.
See also: Authentication overview, Tokens API overview.
Last updated
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
Request
curl -X POST "https://api.mattermode.com/v1/tokens/{id}/revoke"fetch("https://api.mattermode.com/v1/tokens/{id}/revoke", { method: "POST"})package mainimport ( "fmt" "net/http" "io/ioutil")func main() { url := "https://api.mattermode.com/v1/tokens/{id}/revoke" req, _ := http.NewRequest("POST", url, nil) 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",}resp = requests.post( "https://api.mattermode.com/v1/tokens/id_placeholder/revoke", headers=headers,)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;HttpClient client = HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(10)) .build();HttpRequest.Builder requestBuilder = HttpRequest.newBuilder() .uri(URI.create("https://api.mattermode.com/v1/tokens/{id}/revoke")) .POST() .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 client = new HttpClient();var response = await client.PostAsync("https://api.mattermode.com/v1/tokens/{id}/revoke");var responseBody = await response.Content.ReadAsStringAsync();curl --request POST 'https://api.mattermode.com/v1/tokens/id_placeholder/revoke' \ --header 'Authorization: Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc' \ --header 'Matter-Version: 2026-06-10' \ --header 'Idempotency-Key: ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b'const response = await fetch("https://api.mattermode.com/v1/tokens/id_placeholder/revoke", { method: "POST", headers: { "Authorization": "Bearer sk_test_4eC39HqLyjWDarjtT1zdp7dc", "Matter-Version": "2026-06-10", "Idempotency-Key": "ee7c3a9b-3f1a-4d8e-9b2a-7c5e1f0a2d4b", },});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": "tok_4Kj2m8pQ",
"object": "token",
"tier": 0,
"scopes": [
{}
],
"principal": {
"human_id": "usr_4Kj2m8pQ"
},
"limits": {},
"api_version": "2026-05-01",
"revoked_at": 0,
"last_used_at": 0,
"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
}