---
title: "revoke_token"
description: "Generated reference for the management action revoke_token: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/revoke-token
order: 44
visibility: public
redirects_from: ["/reference/actions/revoke-connection"]
---

# revoke\_token

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/revoke_token`, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool `revoke_token`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

Revoke one API token by `id`, or end one sign\-in connection by `connection`\. Pass exactly one\. A revoked token's later uses are refused\. Ending a connection refuses its access token and renewal at once\. Other connections keep working\. Use `list_tokens` to find the token or connection to end\.

## More about this action

End one connection by its id\. Its access token and its renewal are refused at once; your other connections keep working\.

## Access and action metadata

```json
{
  "name": "revoke_token",
  "resource": "token",
  "tier": "reversible",
  "surface": "account",
  "addresses": [
    "tzcloud"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "End one minted token by its identity; every later presentation is refused. With `connection` it ends a connection: End one connection by its id: its refresh and its access token are refused at once, and every other connection remains.",
  "annotations": {
    "readOnlyHint": false,
    "destructiveHint": true,
    "openWorldHint": false
  }
}
```

## MCP catalog entry

```json
{
  "name": "revoke_token",
  "title": "Revoke access token",
  "tier": "reversible",
  "summary": "Revoke one API token by `id`, or end one sign-in connection by `connection`. Pass exactly one. A revoked token's later uses are refused. Ending a connection refuses its access token and renewal at once. Other connections keep working. Use `list_tokens` to find the token or connection to end.",
  "owners": [
    "API-L0-05",
    "MAPI-14",
    "API-L0-21",
    "ACS-L0-11",
    "MCP-10"
  ],
  "scenario": "API-L0-05"
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \[\] |
| /<wbr>properties/<wbr>id | Your token's id, as `list_tokens` and the minting response give it\. One of `id` and `connection` is required\.<br><br>Type: string |
| /<wbr>properties/<wbr>connection | The connection to end, by the id `list_tokens` answers under `connections`, in place of `id`\.<br><br>Type: string |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>token | Type: object<br>Required fields: \["id","revoked\_at"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>id | Type: string |
| /<wbr>properties/<wbr>token/<wbr>properties/<wbr>revoked\_at | Type: string |
| /<wbr>properties/<wbr>connection | Type: object<br>Required fields: \["id","client\_id","revoked\_at","sessions\_ended"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>connection/<wbr>properties/<wbr>id | Type: string |
| /<wbr>properties/<wbr>connection/<wbr>properties/<wbr>client\_id | Type: string |
| /<wbr>properties/<wbr>connection/<wbr>properties/<wbr>revoked\_at | Type: string |
| /<wbr>properties/<wbr>connection/<wbr>properties/<wbr>sessions\_ended | How many access\-token session rows of the connection your call ended\.<br><br>Type: integer |
| /<wbr>properties/<wbr>detail | Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "required": [],
    "properties": {
      "id": {
        "type": "string",
        "description": "Your token's id, as `list_tokens` and the minting response give it. One of `id` and `connection` is required."
      },
      "connection": {
        "type": "string",
        "description": "The connection to end, by the id `list_tokens` answers under `connections`, in place of `id`."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "token": {
        "type": "object",
        "required": [
          "id",
          "revoked_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "revoked_at": {
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "connection": {
        "type": "object",
        "required": [
          "id",
          "client_id",
          "revoked_at",
          "sessions_ended"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "client_id": {
            "type": "string"
          },
          "revoked_at": {
            "type": "string"
          },
          "sessions_ended": {
            "type": "integer",
            "description": "How many access-token session rows of the connection your call ended."
          }
        },
        "additionalProperties": false
      },
      "detail": {
        "type": "string"
      }
    },
    "additionalProperties": false
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
