# AUTO-GENERATED tier-A mirror spec — do not edit. # Source: openapi/runtime/secrets.yaml (runtime 0.71.2) # + policy: openapi/mirror-policies/secrets.json # Regenerate: node scripts/generate-mirror-specs.mjs openapi: 3.0.3 info: title: naturali.ai — Secrets API version: 1.0.0 description: >- Secrets: encrypted, write-only project credentials — the API keys an AI provider authenticates with. A fully runtime-backed module — this spec is generated verbatim from the runtime's own, re-rooted under /v1/projects/{project_id}. The project in the path is authorized by naturali and enforced upstream by the project's scoped credential. This module mirrors the upstream runtime verbatim (tier A, #304): paths are the runtime's own re-rooted under /v1/projects/{project_id}, and every field, method, status code and error shape passes through unchanged. Errors raised by the runtime arrive in its envelope; errors raised by naturali itself (authentication, project resolution, an unreachable runtime) use naturali's. contact: name: naturali.ai url: https://naturali.ai servers: - url: "{baseUrl}" description: Host of your naturali.ai deployment; every path carries the /v1 prefix. variables: baseUrl: description: Base host URL. default: https://api.naturali.ai tags: - name: Secrets description: Manage secrets security: - bearerAuth: [] - oauth2: - mcp:access paths: /v1/projects/{project_id}/secrets: get: tags: - Secrets summary: List secrets description: Returns a list of secrets for a project operationId: listSecrets parameters: - name: limit in: query description: Number of results per page schema: type: integer minimum: 1 maximum: 100 default: 50 - name: offset in: query description: Number of results to skip schema: type: integer default: 0 responses: "200": description: List of secrets content: application/json: schema: type: object required: - data - total - limit - offset properties: data: type: array items: type: object properties: id: type: string name: type: string has_value: type: boolean description: Whether an encrypted value is stored for this secret project_id: x-naturali-ref: projects type: string created_at: type: string format: date-time updated_at: type: string format: date-time total: type: integer limit: type: integer offset: type: integer "401": description: Unauthorized "403": description: Forbidden "500": description: Internal server error post: tags: - Secrets summary: Create a secret description: Creates a new encrypted secret in a project operationId: createSecret x-naturali-agent-exclude: true requestBody: required: true content: application/json: schema: type: object required: - name - value additionalProperties: false properties: name: type: string description: Secret name example: DATABASE_PASSWORD value: type: string description: Secret value (will be encrypted) example: supersecretpassword responses: "201": description: Secret created successfully content: application/json: schema: type: object properties: id: type: string name: type: string has_value: type: boolean description: Whether an encrypted value is stored for this secret project_id: x-naturali-ref: projects type: string created_at: type: string format: date-time updated_at: type: string format: date-time "400": description: Bad request (missing required fields) "401": description: Unauthorized "403": description: Forbidden "500": description: Internal server error parameters: - $ref: "#/components/parameters/ProjectId" /v1/projects/{project_id}/secrets/{secret_id}: get: tags: - Secrets summary: Get a secret description: Returns a specific secret operationId: getSecret parameters: - name: secret_id in: path required: true description: Secret ID schema: type: string example: sec_V1StGXR8Z5jdHi6B responses: "200": description: Secret details content: application/json: schema: type: object properties: id: type: string name: type: string has_value: type: boolean description: Whether an encrypted value is stored for this secret project_id: x-naturali-ref: projects type: string created_at: type: string format: date-time updated_at: type: string format: date-time "401": description: Unauthorized "403": description: Forbidden "404": description: Secret not found patch: tags: - Secrets summary: Update a secret description: Updates a secret's name and/or value operationId: updateSecret x-naturali-agent-exclude: true parameters: - name: secret_id in: path required: true description: Secret ID schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: type: string description: New secret name value: type: string description: New secret value responses: "200": description: Secret updated successfully "400": description: Bad request "401": description: Unauthorized "403": description: Forbidden "404": description: Secret not found delete: tags: - Secrets summary: Delete a secret description: Deletes a secret operationId: deleteSecret x-naturali-agent-exclude: true parameters: - name: secret_id in: path required: true description: Secret ID schema: type: string - name: force in: query required: false description: Delete the secret even when AI providers reference it, destroying those providers too. Without it a referenced secret answers SECRET_HAS_DEPENDENTS. schema: type: boolean default: false responses: "200": description: Secret deleted successfully "401": description: Unauthorized "403": description: Forbidden "404": description: Secret not found parameters: - $ref: "#/components/parameters/ProjectId" components: parameters: ProjectId: name: project_id in: path required: true description: Project public ID (proj_ prefix). schema: type: string example: proj_V1StGXR8Z5jdHi6B securitySchemes: bearerAuth: type: http scheme: bearer description: A naturali API key (nat_sk_…) or a session JWT. oauth2: type: oauth2 description: "A connected app's OAuth access token, issued by this API's authorization server (discovery: /.well-known/oauth-authorization-server). Its one scope carries every operation, confined to the projects the user chose when approving the app." flows: authorizationCode: authorizationUrl: https://api.naturali.ai/authorize tokenUrl: https://api.naturali.ai/token refreshUrl: https://api.naturali.ai/token scopes: mcp:access: Every operation this API serves, on the projects the grant covers.