{ "openapi": "3.1.0", "info": { "title": "CertLocker API", "version": "1.0.0", "description": "The CertLocker API covers certificate management, secret storage, token lifecycle, and the Agent API for AI agents and automation.\n\n## Authentication\n\nAll endpoints require an `x-api-token` header. For human/app access use a standard token; for AI agents use a scoped MCP token (max 90-day TTL).\n\n## Agent flows\n\n1. `POST /api/agent/session/start`\n2. `GET /api/agent/permissions` \u2014 check available scopes\n3. Use metadata endpoints before raw-value endpoints\n4. `POST /api/agent/ssh/session?dryRun=true` before any SSH request\n5. `POST /api/agent/token/revoke` when done\n\n## Privileged endpoints\n\nEndpoints marked \u26a0\ufe0f **Privileged** return raw values (secret text, private keys). Every call is audited. Prefer metadata endpoints where the raw value is not needed.", "contact": { "name": "CertLocker Support", "url": "https://certlocker.io/contact", "email": "support@certlocker.io" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-CertLocker-Proprietary", "url": "https://certlocker.io/legal" } }, "servers": [ { "url": "{apiBaseUrl}", "description": "CertLocker API", "variables": { "apiBaseUrl": { "default": "https://trust.certlocker.io", "description": "Base URL configured by CERTLOCKER_PUBLIC_API_BASE_URL" } } } ], "security": [ { "ApiToken": [] } ], "tags": [ { "name": "Agent API", "description": "AI agent and MCP integration. All endpoints require a scoped MCP token." }, { "name": "Certificates", "description": "Certificate fetch and metadata. Fetch-bundle returns the private key \u2014 treat as privileged." }, { "name": "Secrets", "description": "Secret storage management. Fetch returns the raw value \u2014 treat as privileged." }, { "name": "Tokens", "description": "Token lifecycle: get details, list available hosts." } ], "components": { "securitySchemes": { "ApiToken": { "type": "apiKey", "in": "header", "name": "x-api-token", "description": "CertLocker token. For agents: a scoped MCP token (max 90-day TTL). Do not embed in source code \u2014 use a secrets manager." } }, "responses": { "AccessDenied": { "description": "Forbidden \u2014 token lacks required scope or group access", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentDenyResponseDTO" } } } }, "Unauthorized": { "description": "Unauthorized \u2014 missing or invalid x-api-token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } } }, "schemas": { "AgentApprovalRequestDTO": { "type": "object", "properties": { "payload": { "type": "string" } } }, "AgentAuditEventRequestDTO": { "type": "object", "properties": { "action": { "type": "string" }, "message": { "type": "string" }, "resource_id": { "type": "string" } } }, "AgentProbeRequestDTO": { "type": "object", "properties": { "host": { "type": "string" }, "port": { "type": "integer", "format": "int32" }, "dry_run": { "type": "boolean" } } }, "AgentSessionStartRequestDTO": { "type": "object", "properties": { "metadata": { "type": "object", "additionalProperties": { "type": "string" } } } }, "AgentSshSessionRequestDTO": { "type": "object", "properties": { "host_id": { "type": "string" }, "dry_run": { "type": "boolean" } } }, "AssetStatus": { "type": "string", "enum": [ "ACTIVE", "SUSPENDED", "EXPIRED", "REVOKED" ] }, "SecretType": { "type": "string", "enum": [ "PEM", "PASSWORD", "CREDENTIALS", "CONFIGURATION" ] }, "SuccessResponseDO": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "certificate": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/AssetStatus" }, "groups": { "type": "array", "items": { "type": "string" } }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "date_created": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50" ] }, "date_updated": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50" ] }, "primary_domain": { "type": "string" }, "san_domains": { "type": "array", "items": { "type": "string" } }, "not_before": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50" ] }, "entries": { "type": "integer", "format": "int32" }, "serial_number": { "type": "string" }, "public_key_algo": { "type": "string" }, "issuer_cn": { "type": "string" }, "issuer_o": { "type": "string" }, "fingerprint_sha256": { "type": "string" }, "fingerprint_sha1": { "type": "string" }, "cert_validation": { "$ref": "#/components/schemas/CertValidation" } } }, "error": { "type": "object", "properties": { "error_message": { "type": "string" } } }, "host": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/AssetStatus" }, "groups": { "type": "array", "items": { "type": "string" } }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "date_created": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50" ] }, "date_updated": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50" ] }, "ip_address": { "type": "string" }, "port": { "type": "integer", "format": "int32" }, "operating_system": { "type": "string" }, "secret_id": { "type": "string" }, "bastion_id": { "type": "string" } } }, "hosts": { "type": "object", "properties": { "hosts": { "type": "array", "items": { "$ref": "#/components/schemas/host" } } } }, "secret": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/AssetStatus" }, "groups": { "type": "array", "items": { "type": "string" } }, "secret_type": { "$ref": "#/components/schemas/SecretType" } } }, "secret1": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/AssetStatus" }, "groups": { "type": "array", "items": { "type": "string" } }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "date_created": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50" ] }, "date_updated": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50" ] }, "secret_type": { "$ref": "#/components/schemas/SecretType" } } }, "token": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "$ref": "#/components/schemas/AssetStatus" }, "groups": { "type": "array", "items": { "type": "string" } }, "created_by": { "type": "string" }, "updated_by": { "type": "string" }, "date_created": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50" ] }, "date_updated": { "type": "string", "format": "date-time", "examples": [ "2022-03-10T12:15:50" ] }, "single_use": { "type": "boolean" }, "protocols": { "type": "array", "items": { "$ref": "#/components/schemas/Protocol" } }, "token_type": { "$ref": "#/components/schemas/TokenType" }, "hosts": { "type": "array", "items": { "type": "string" } }, "group_access": { "type": "array", "items": { "type": "string" } }, "secret_id": { "type": "string" }, "access_code": { "type": "string" }, "bastion_id": { "type": "string" }, "cert_id": { "type": "string" }, "auto_rotate": { "type": "boolean" }, "user_id": { "type": "string" } } }, "AgentDenyResponseDTO": { "type": "object", "description": "Authorization denial response returned when an agent token lacks a required permission.", "properties": { "allowed": { "type": "boolean", "example": false }, "reason": { "type": "string" }, "required_permission": { "type": "string" } } }, "CertValidation": { "type": "string", "description": "Certificate validation status.", "enum": [ "VALID", "INVALID", "UNKNOWN" ] }, "Protocol": { "type": "string", "description": "Protocol enabled for a token or host.", "enum": [ "SSH", "HTTPS", "MCP" ] }, "TokenType": { "type": "string", "description": "CertLocker token type.", "enum": [ "SECRET", "SSH", "MCP", "API" ] } } }, "paths": { "/api/agent/approval/request": { "post": { "summary": "Request human approval", "tags": [ "Agent API" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentApprovalRequestDTO" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Submits an approval request to a human operator. Required before dangerous or production-scoped actions. Requires `approval:request` scope." } }, "/api/agent/audit/event": { "post": { "summary": "Write agent audit event", "tags": [ "Agent API" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentAuditEventRequestDTO" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Writes an agent-authored audit event. Requires `audit:write` scope." } }, "/api/agent/certificates/{id}": { "get": { "summary": "Get certificate by id or name", "tags": [ "Agent API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Returns certificate metadata including domain, expiry, and fingerprint. Does not return private key material. Requires `certificate:read` scope." } }, "/api/agent/hosts": { "get": { "summary": "List allowed hosts", "tags": [ "Agent API" ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Lists allowed hosts visible to this token. Host names and ids only \u2014 no credentials." } }, "/api/agent/permissions": { "get": { "summary": "Agent permissions", "tags": [ "Agent API" ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Returns the scopes and group access granted to this token. Call this first to understand what actions are available before attempting them." } }, "/api/agent/probes": { "post": { "summary": "Create probe \u2014 use dryRun=true to validate permissions without creating a probe", "tags": [ "Agent API" ], "parameters": [ { "description": "Validate only, do not create probe", "in": "query", "name": "dryRun", "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentProbeRequestDTO" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Creates a connectivity probe for the given host and port. Requires `probe:create` scope. Use `dryRun=true` to validate permissions without creating a probe." } }, "/api/agent/profile": { "get": { "summary": "Agent profile", "tags": [ "Agent API" ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Returns the agent name, id, owner, and risk level. Requires an active session." } }, "/api/agent/secrets": { "get": { "summary": "List allowed secrets", "tags": [ "Agent API" ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Lists secret names and ids visible to this token. Does not return raw values." } }, "/api/agent/secrets/{id}": { "get": { "summary": "Get secret by id or name \u2014 returns raw value; requires explicit authorization", "tags": [ "Agent API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "\u26a0\ufe0f **Privileged.** Returns the raw secret value. Requires `secret:read` scope. This action is audited. Prefer `GET /api/agent/secrets/{id}/metadata` unless the value is explicitly needed.", "x-certlocker-privileged": true } }, "/api/agent/secrets/{id}/metadata": { "get": { "summary": "Get secret metadata (id, name, expiry) \u2014 never returns raw secret value", "tags": [ "Agent API" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Returns secret id, name, and expiry. Never returns the raw value. Use this to inspect a secret safely before deciding whether to fetch the value." } }, "/api/agent/session/end": { "post": { "summary": "End agent session", "tags": [ "Agent API" ], "responses": { "201": { "description": "Created" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Ends the current agent session." } }, "/api/agent/session/start": { "post": { "summary": "Start agent session", "tags": [ "Agent API" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSessionStartRequestDTO" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Starts an agent session and returns a session id. The session id must be included in subsequent requests. Requires a valid MCP token in `x-api-token`." } }, "/api/agent/ssh/session": { "post": { "summary": "Request SSH session \u2014 use dryRun=true to validate permissions without creating a session", "tags": [ "Agent API" ], "parameters": [ { "description": "Validate only, do not create session", "in": "query", "name": "dryRun", "schema": { "type": "boolean" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentSshSessionRequestDTO" } } }, "required": true }, "responses": { "201": { "description": "Created" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "\u26a0\ufe0f **Dangerous.** Requests a JIT SSH session for an allowed host. Requires `ssh_session:request` scope. This action is audited. Use `dryRun=true` to validate permissions without creating a session." } }, "/api/agent/token/revoke": { "post": { "summary": "Revoke the current MCP token \u2014 the token cannot be used after this call", "tags": [ "Agent API" ], "responses": { "201": { "description": "Created" }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "description": "Immediately revokes the MCP token used in this request. No further calls can be made with it after revocation." } }, "/api/v1/cert/fetch-bundle/{token}": { "get": { "summary": "Fetch Certificate, with the private key.", "description": "\u26a0\ufe0f **Privileged.** Returns the full certificate bundle including private key as PEM. Use only when private key material is explicitly required. This action is audited.", "tags": [ "Certificates" ], "parameters": [ { "description": "token", "required": true, "name": "token", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fetch Certificate", "content": { "text/plain": {} } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "x-certlocker-privileged": true } }, "/api/v1/cert/fetch/{token}": { "get": { "summary": "Fetch Certificate", "description": "Returns the certificate as PEM text. Public certificate only \u2014 no private key.", "tags": [ "Certificates" ], "parameters": [ { "description": "token", "required": true, "name": "token", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fetch Certificate", "content": { "text/plain": {} } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } } } }, "/api/v1/cert/get/{token}": { "get": { "summary": "Get certificate details", "description": "Returns certificate metadata: id, name, status, groups, validity dates.", "tags": [ "Certificates" ], "parameters": [ { "description": "token", "required": true, "name": "token", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Certificate Details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/certificate" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "404": { "description": "Not found" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } } } }, "/api/v1/secret/create": { "post": { "summary": "Create secret", "description": "Creates a new secret. Returns confirmation with the secret id.", "tags": [ "Secrets" ], "requestBody": { "description": "secret", "content": { "*/*": { "schema": { "$ref": "#/components/schemas/secret" } } }, "required": true }, "responses": { "200": { "description": "secret details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secret1" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "404": { "description": "Not found" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } } } }, "/api/v1/secret/fetch/{secret}": { "get": { "summary": "Fetch Secret", "description": "\u26a0\ufe0f **Privileged.** Returns the raw secret value as plain text. This action is audited. Use `GET /api/v1/secret/get/{secret}` for metadata-only access.", "tags": [ "Secrets" ], "parameters": [ { "description": "secret", "required": true, "name": "secret", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Fetch Secret", "content": { "text/plain": {}, "application/json": {} } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } }, "x-certlocker-privileged": true } }, "/api/v1/secret/get/{secret}": { "get": { "summary": "Get secret", "description": "Returns secret metadata: id, name, status, groups, created_by. Never returns the raw value.", "tags": [ "Secrets" ], "parameters": [ { "description": "secret", "required": true, "name": "secret", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "secret Details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secret1" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "404": { "description": "Not found" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } } } }, "/api/v1/secret/lookup": { "get": { "summary": "Lookup secret", "description": "Looks up a secret by name. Returns metadata only, no raw value.", "tags": [ "Secrets" ], "parameters": [ { "description": "Any number of dynamic query parameters (e.g. ?name=my-secret&status=EXPIRED)", "in": "query", "name": "name", "required": true, "schema": { "type": "string" }, "style": "form" } ], "responses": { "200": { "description": "secret Details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/secret1" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "404": { "description": "Not found" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } } } }, "/api/v1/secret/revoke/{secret}": { "post": { "summary": "Revoke secret", "description": "Revokes a secret, preventing further use.", "tags": [ "Secrets" ], "parameters": [ { "description": "secret", "required": true, "name": "secret", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "If successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuccessResponseDO" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "404": { "description": "Not found" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } } } }, "/api/v1/token/get/{token}": { "get": { "summary": "Get Token", "description": "Returns token metadata: id, name, status, type, groups, expiry.", "tags": [ "Tokens" ], "parameters": [ { "description": "token", "required": true, "name": "token", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Token Details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/token" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } } } }, "/api/v1/token/hosts-available/{token}": { "post": { "summary": "Hosts Available", "description": "Lists the hosts available for use with a given token.", "tags": [ "Tokens" ], "parameters": [ { "description": "token", "required": true, "name": "token", "in": "path", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of hosts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/hosts" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error" } } } }, "403": { "description": "Missing or invalid x-api-token" }, "429": { "description": "Too many requests" }, "500": { "description": "Internal Error" } } } } } }