> 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. # Read tool credential metadata GET https://api.v2.rasen.ai/v1/secrets/{secret_id} Metadata and reference counts only. Never returns the value, a hash or a fingerprint. Reference: https://docs.v2.rasen.ai/api-reference/secrets/get ## 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. ## Response ### 200 Read tool credential metadata. - `id` (string, required) — Opaque sec identifier. Do not parse its contents. - `resource_key` (string, required, nullable) — Optional caller-chosen resource key: an opaque external identifier that matches your own record (for example a CRM ID, a configuration-file ID or a UUID) to this resource. Rasen still generates the canonical id; use id in paths and references. Case-sensitive, compared exactly, never normalized or parsed. 1-128 characters from A-Z a-z 0-9 . _ : ~ - and starting with a letter or digit; UUIDs and ULIDs are valid. Unique per resource type within one workspace; separate environment workspaces can reuse the same key. Set only at creation and immutable afterwards. A create with a key that already exists returns 409 resource_key_conflict with details.existing_id; it never updates or returns the existing resource. Not an Idempotency-Key: that header identifies one request intent for 24 hours, and a same-intent replay returns its original receipt before the resource-key check runs. Uniqueness includes archived resources. A key becomes free again only after its resource is permanently deleted or erased (a deleted secret or a deleted knowledge source); archive never frees it. - `name` (string, required) — Workspace-unique handle among secrets that are not deleted. A label, not the resource key. Deletion frees the name and the resource_key. - `purpose` (string, required) — Consumer type the credential may be released to. A webhook_tool secret cannot be used by an MCP server, and the reverse. Open response vocabulary. Preserve unknown values; never assume they mean success. - `material_kind` (string, required) — A descriptive label that does not change how the value is sent. Rasen sends the stored value unchanged as the header value for a webhook secret header, or as "Bearer \" for an MCP server with auth=bearer, or as the header value for auth=secret\_header. For basic\_auth, store the complete header value, for example "Basic \", and use a secret header named Authorization. No kind and auth-mode pair is refused. Open response vocabulary. Preserve unknown values; never assume they mean success. - `state` (string, required) — revoked means every version is revoked. Open response vocabulary. Preserve unknown values; never assume they mean success. - `latest_version` (integer, required) — Highest version number. Not an implicit binding target: consumers pin exact versions. - `active_version_count` (integer, required) - `created_at` (datetime, required) - `updated_at` (datetime, required) - `last_rotated_at` (datetime, required, nullable) - `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. ### 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 **Response** ```json { "id": "sec_01j00000000000000000000000", "resource_key": "3f8e5a0c-9d1b-4c7e-a2f4-6b0d9e1c7a55", "name": "example", "purpose": "webhook_tool", "material_kind": "api_key", "state": "active", "latest_version": 1, "active_version_count": 0, "created_at": "2026-09-25T10:00:00Z", "updated_at": "2026-09-25T10:06:00Z", "last_rotated_at": "2026-09-25T10:30:00Z", "usage": { "draft_binding_count": 0, "published_version_count": 0, "live_version_count": 0 } } ``` **SDK Code** ```python secrets_get_example import requests url = "https://api.v2.rasen.ai/v1/secrets/secret_id" headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript secrets_get_example const url = 'https://api.v2.rasen.ai/v1/secrets/secret_id'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```ruby secrets_get_example require 'uri' require 'net/http' url = URI("https://api.v2.rasen.ai/v1/secrets/secret_id") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java secrets_get_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.v2.rasen.ai/v1/secrets/secret_id") .header("Authorization", "Bearer ") .asString(); ``` ```php secrets_get_example request('GET', 'https://api.v2.rasen.ai/v1/secrets/secret_id', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp secrets_get_example using RestSharp; var client = new RestClient("https://api.v2.rasen.ai/v1/secrets/secret_id"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift secrets_get_example import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.v2.rasen.ai/v1/secrets/secret_id")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers 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() ```