> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.v2.rasen.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.v2.rasen.ai/_mcp/server.

# Emergency revoke a credential version

POST https://api.v2.rasen.ai/v1/secrets/{secret_id}/versions/{version}/revoke
Content-Type: application/json

Blocks every later use of this version immediately, including by live published agents, without publication or a draft edit. Every later tool call that would use the revoked version is refused, including later tool calls inside a call that is already running (its MCP session is closed); an external action already performed is not undone. Refused tool calls appear as failed tool outcomes with credential\_unavailable; the call itself continues. Irreversible: rotate, rebind and publish to recover. New draft references and publications that pin a revoked version refuse with credential\_unavailable. Rollback never re-enables a revoked version. Revoking an already revoked version returns its current state. Use GET /secrets/\{secret\_id}/references to find affected agents.

Reference: https://docs.v2.rasen.ai/api-reference/secrets/versions/revoke

## Authentication

- `Authorization` header (bearer token, required) — Create and manage workspace-owned keys through the existing app session routes, outside this public API. Creator and manager identities are audit actors only. Key validity follows workspace policy, expiry and explicit revocation, independently of creator membership. Do not include a workspace-selection header.

## Request

### Path parameters

- `secret_id` (string, required) — Resource identity within the authenticated workspace.
- `version` (integer, required) — Secret version number.

### Headers

- `Idempotency-Key` (string, required) — Stable key per logical intent, 1–255 printable characters. Persist it before sending. Retry the same key/body after an uncertain result for 24 hours. A changed body conflicts. Beyond retention, reconcile the resource before retrying; this is not permanent deduplication. Current authorization is rechecked on replay. Evaluation order: authenticate and check current authorization; look up intent; replay its stored receipt before checking the current revision; only a new intent evaluates If-Match and executes. Fingerprint includes method, path, body and original If-Match. A changed request returns idempotency_key_reused. The server stores only a keyed (HMAC) fingerprint, and no error or response ever returns a fingerprint or hash of a request. In-flight intent returns 409 idempotency_in_progress with Retry-After; retry the same intent after reconciliation. Receipts describe that attempt, not current resource state. A replay returns the original status code and body, with the response header Idempotent-Replayed: true.

### Body (application/json)

This endpoint expects a SecretRevokeRequest.

- `reason` (enum, required)
  - Allowed values: `compromised`, `requested`

## Response

### 200

Emergency revoke a credential version.

- `secret_id` (string, required) — Opaque sec identifier. Do not parse its contents.
- `version` (integer, required)
- `state` (string, required) — Open response vocabulary. Preserve unknown values; never assume they mean success.
- `created_at` (datetime, required)
- `revoked_at` (datetime, required, nullable)
- `revoke_reason` (string, required, nullable) — Reason given to revokeSecretVersion. Open response vocabulary. Preserve unknown values; never assume they mean success.
- `usage` (SecretUsage, required) — Reference counts at response time. Use GET /secrets/\{secret\_id}/references for the exact consumers.

## Errors

### 400 Bad Request Error

Invalid input or cursor. Correct the request.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 401 Unauthorized Error

Invalid, expired or revoked API key. Creator departure or membership changes do not invalidate a workspace key.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 403 Forbidden Error

Operation not allowed by current credential or workspace access.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 404 Not Found Error

Resource absent or not visible in this workspace.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 409 Conflict Error

Conflict. Not retryable: read the current state, fix the request and send a new request. The one exception is idempotency_in_progress, which carries Retry-After: wait, then resend the identical request with the same Idempotency-Key. The operation lists its codes in x-error-codes; branch on error.code and, for conflict, error.details.reason.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 413 Content Too Large Error

Body or upload exceeds its allowed limit.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 429 Too Many Requests Error

Rate limited. Respect Retry-After and retry the same intent where permitted.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 500 Internal Server Error

Internal error. The effect may have happened. Retry the same request with the same Idempotency-Key; read the resource before creating a new intent. For an operation that takes an Idempotency-Key, a client retry with the same key is safe: the server replays the stored outcome if the first attempt took effect; if the first attempt had no effect, the retry performs the operation once. Never retry with a new key.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

### 503 Service Unavailable Error

Service unavailable. Respect Retry-After where present. For an operation that takes an Idempotency-Key, a client retry with the same key is safe: the server replays the stored outcome if the first attempt took effect; if the first attempt had no effect, the retry performs the operation once. Never retry with a new key.

- `error` (ErrorResponseError, required) — Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

## Types

### SecretUsage

Reference counts at response time. Use GET /secrets/\{secret\_id}/references for the exact consumers.

- `draft_binding_count` (integer, required) — Current draft tool headers and MCP server connections that reference this secret or version.
- `published_version_count` (integer, required) — Retained published agent versions that pin this secret or version.
- `live_version_count` (integer, required) — Of those, versions that are live for new calls now.

### ErrorResponseError

Only code and message are required. Rasen sends details, request_id and retry on every error, but clients must parse an error that lacks them, so a typed error is never lost to a parsing failure.

- `code` (string, required) — Stable code. Branch on code (and details.reason for conflict), never on message. Each code has one HTTP status; see components.x-error-catalog.
- `message` (string, required) — Safe description; no provider payload or submitted secrets.
- `details` (map from string to any, optional) — Safe code-specific details. The public fields for each code are listed in components.x-error-catalog. Details never contain a request fingerprint, a hash of a request, secret material or another tenant's data. forbidden may include required_capabilities (a list).
- `request_id` (string, optional) — Same value as the X-Request-Id header. Quote it to support.
- `retry` (string, optional) — Retry class of this code: no (fix the request or state first), yes (retry the same request and the same Idempotency-Key), retry_after (wait for Retry-After, then retry the same request). Open response vocabulary. Preserve unknown values; never assume they mean success.

## Examples

**Request**

```json
{
  "reason": "compromised"
}
```

**Response**

```json
{
  "secret_id": "sec_01j00000000000000000000000",
  "version": 1,
  "state": "active",
  "created_at": "2026-09-25T10:00:00Z",
  "revoked_at": "2026-09-25T11:00:00Z",
  "revoke_reason": "compromised",
  "usage": {
    "draft_binding_count": 0,
    "published_version_count": 0,
    "live_version_count": 0
  }
}
```

**SDK Code**

```python secrets_versions_revoke_example
import requests

url = "https://api.v2.rasen.ai/v1/secrets/secret_id/versions/1/revoke"

payload = { "reason": "compromised" }
headers = {
    "Idempotency-Key": "intent-appointment-001",
    "Authorization": "Bearer <api_key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript secrets_versions_revoke_example
const url = 'https://api.v2.rasen.ai/v1/secrets/secret_id/versions/1/revoke';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': 'intent-appointment-001',
    Authorization: 'Bearer <api_key>',
    'Content-Type': 'application/json'
  },
  body: '{"reason":"compromised"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```ruby secrets_versions_revoke_example
require 'uri'
require 'net/http'

url = URI("https://api.v2.rasen.ai/v1/secrets/secret_id/versions/1/revoke")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = 'intent-appointment-001'
request["Authorization"] = 'Bearer <api_key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"compromised\"\n}"

response = http.request(request)
puts response.read_body
```

```java secrets_versions_revoke_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.v2.rasen.ai/v1/secrets/secret_id/versions/1/revoke")
  .header("Idempotency-Key", "intent-appointment-001")
  .header("Authorization", "Bearer <api_key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"compromised\"\n}")
  .asString();
```

```php secrets_versions_revoke_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.v2.rasen.ai/v1/secrets/secret_id/versions/1/revoke', [
  'body' => '{
  "reason": "compromised"
}',
  'headers' => [
    'Authorization' => 'Bearer <api_key>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => 'intent-appointment-001',
  ],
]);

echo $response->getBody();
```

```csharp secrets_versions_revoke_example
using RestSharp;

var client = new RestClient("https://api.v2.rasen.ai/v1/secrets/secret_id/versions/1/revoke");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "intent-appointment-001");
request.AddHeader("Authorization", "Bearer <api_key>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"reason\": \"compromised\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift secrets_versions_revoke_example
import Foundation

let headers = [
  "Idempotency-Key": "intent-appointment-001",
  "Authorization": "Bearer <api_key>",
  "Content-Type": "application/json"
]
let parameters = ["reason": "compromised"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.v2.rasen.ai/v1/secrets/secret_id/versions/1/revoke")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```