{ "openapi": "3.1.0", "info": { "title": "KeyEnv API", "description": "KeyEnv is a secure secrets management platform for development teams.\n\n## Authentication\n\nAll API endpoints (except `/health` and `/api/v1`) require authentication via:\n\n1. **Clerk JWT Token** - For user authentication from the web dashboard\n - Include in the `Authorization` header as `Bearer `\n\n2. **Service Token** - For CI/CD and programmatic access\n - Include in the `Authorization` header as `Bearer `\n - Service tokens are scoped to a specific team and can have read/write permissions\n\n## Rate Limiting\n\nAPI requests are rate-limited to prevent abuse. The default limit is 100 requests per minute per IP address.\n\n## Encryption\n\nAll secret values are encrypted using AES-256-GCM before being stored. The encryption key is managed server-side.\n", "version": "1.0.0", "contact": { "email": "support@keyenv.dev" }, "license": { "name": "Proprietary", "url": "https://keyenv.dev/terms" } }, "servers": [ { "url": "https://api.keyenv.dev", "description": "Production server" }, { "url": "http://localhost:7080", "description": "Local development server" } ], "tags": [ { "name": "Health", "description": "Health check endpoints" }, { "name": "Auth", "description": "Authentication and user sync" }, { "name": "Users", "description": "User management" }, { "name": "Teams", "description": "Team management and collaboration" }, { "name": "Invitations", "description": "Team invitation management" }, { "name": "Projects", "description": "Project management" }, { "name": "Environments", "description": "Environment management within projects" }, { "name": "Secrets", "description": "Secret management (encrypted key-value pairs)" }, { "name": "Permissions", "description": "Environment-level access control" }, { "name": "Tokens", "description": "Service token management for CI/CD" }, { "name": "Rotations", "description": "Automated credential rotation for database secrets" }, { "name": "Scans", "description": "Secret scanning for detecting hardcoded secrets" }, { "name": "ESO", "description": "External Secrets Operator (ESO) webhook endpoints for Kubernetes integration.\nThese endpoints allow ESO to fetch secrets from KeyEnv and sync them to Kubernetes Secrets.\n\n**Authentication:** Service token required (user authentication not supported).\n\nSee the [Kubernetes ESO Integration Guide](https://docs.keyenv.dev/integrations/kubernetes-eso) for setup instructions.\n" }, { "name": "Audit", "description": "Audit log access" }, { "name": "Billing", "description": "Billing and usage information" }, { "name": "CLI", "description": "CLI authentication endpoints for device authorization flow" }, { "name": "Account", "description": "GDPR and account management" } ], "paths": { "/health": { "get": { "tags": [ "Health" ], "summary": "Health check", "description": "Returns the health status of the API server", "operationId": "healthCheck", "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "503": { "description": "Service is degraded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/api/v1": { "get": { "tags": [ "Health" ], "summary": "API info", "description": "Returns basic API information", "operationId": "apiInfo", "responses": { "200": { "description": "API information", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "KeyEnv API v1" }, "version": { "type": "string", "example": "1.0.0" } } } } } } } } }, "/api/v1/auth/sync": { "post": { "tags": [ "Auth" ], "summary": "Sync user from Clerk", "description": "Syncs user data from Clerk to KeyEnv. This should be called after a user signs up\nor logs in to ensure their account exists in KeyEnv. Creates a personal team for\nnew users.\n", "operationId": "authSync", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "User synced successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/users/me": { "get": { "tags": [ "Users" ], "summary": "Get current user", "description": "Returns the currently authenticated user's profile", "operationId": "getCurrentUser", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/teams": { "get": { "tags": [ "Teams" ], "summary": "List teams", "description": "Returns all teams the current user is a member of", "operationId": "listTeams", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of teams", "content": { "application/json": { "schema": { "type": "object", "properties": { "teams": { "type": "array", "items": { "$ref": "#/components/schemas/TeamWithMembers" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Teams" ], "summary": "Create team", "description": "Creates a new team with the current user as owner", "operationId": "createTeam", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTeamRequest" } } } }, "responses": { "201": { "description": "Team created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/teams/{teamId}": { "get": { "tags": [ "Teams" ], "summary": "Get team", "description": "Returns team details including members", "operationId": "getTeam", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "responses": { "200": { "description": "Team details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamWithMembers" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/teams/{teamId}/members": { "post": { "tags": [ "Teams" ], "summary": "Invite team member", "description": "Invites a user to join the team by email", "operationId": "inviteTeamMember", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberRequest" } } } }, "responses": { "201": { "description": "Member invited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/teams/{teamId}/members/{userId}": { "patch": { "tags": [ "Teams" ], "summary": "Update member role", "description": "Updates a team member's role", "operationId": "updateMemberRole", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/userId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRoleRequest" } } } }, "responses": { "200": { "description": "Role updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamMember" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "tags": [ "Teams" ], "summary": "Remove team member", "description": "Removes a member from the team", "operationId": "removeTeamMember", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "204": { "description": "Member removed" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/teams/{teamId}/invitations": { "get": { "tags": [ "Invitations" ], "summary": "List team invitations", "description": "Returns pending invitations for a team", "operationId": "listTeamInvitations", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "responses": { "200": { "description": "List of invitations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TeamInvitation" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/teams/{teamId}/invitations/{invitationId}": { "delete": { "tags": [ "Invitations" ], "summary": "Revoke invitation", "description": "Revokes a pending team invitation", "operationId": "revokeInvitation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Invitation revoked" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/teams/{teamId}/invitations/{invitationId}/resend": { "post": { "tags": [ "Invitations" ], "summary": "Resend invitation", "description": "Resends a pending team invitation email", "operationId": "resendInvitation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "name": "invitationId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Invitation resent" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/invitations": { "get": { "tags": [ "Invitations" ], "summary": "List my invitations", "description": "Returns pending invitations for the current user", "operationId": "listMyInvitations", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of invitations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InvitationPublicInfo" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/invitations/{token}": { "get": { "tags": [ "Invitations" ], "summary": "Get invitation by token", "description": "Returns public information about an invitation", "operationId": "getInvitationByToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitationPublicInfo" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/invitations/{token}/accept": { "post": { "tags": [ "Invitations" ], "summary": "Accept invitation", "description": "Accepts a team invitation and joins the team", "operationId": "acceptInvitation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Invitation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Team" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/projects": { "get": { "tags": [ "Projects" ], "summary": "List projects", "description": "Returns all projects the user has access to through their teams", "operationId": "listProjects", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of projects", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "$ref": "#/components/schemas/Project" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Projects" ], "summary": "Create project", "description": "Creates a new project within a team. Default environments (development, staging, production) are created automatically.", "operationId": "createProject", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectRequest" } } } }, "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/LimitExceeded" } } } }, "/api/v1/projects/{projectId}": { "get": { "tags": [ "Projects" ], "summary": "Get project", "description": "Returns project details including environments", "operationId": "getProject", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" } ], "responses": { "200": { "description": "Project details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectWithEnvironments" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Projects" ], "summary": "Update project", "description": "Updates project name", "operationId": "updateProject", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectRequest" } } } }, "responses": { "200": { "description": "Project updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Projects" ], "summary": "Delete project", "description": "Soft deletes a project and all its environments and secrets", "operationId": "deleteProject", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" } ], "responses": { "204": { "description": "Project deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/projects/{projectId}/environments": { "get": { "tags": [ "Environments" ], "summary": "List environments", "description": "Returns all environments in a project", "operationId": "listEnvironments", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" } ], "responses": { "200": { "description": "List of environments", "content": { "application/json": { "schema": { "type": "object", "properties": { "environments": { "type": "array", "items": { "$ref": "#/components/schemas/Environment" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Environments" ], "summary": "Create environment", "description": "Creates a new environment in a project. Can optionally inherit secrets from another environment.", "operationId": "createEnvironment", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvironmentRequest" } } } }, "responses": { "201": { "description": "Environment created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/LimitExceeded" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}": { "get": { "tags": [ "Environments" ], "summary": "Get environment", "description": "Returns environment details", "operationId": "getEnvironment", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" } ], "responses": { "200": { "description": "Environment details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Environment" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Environments" ], "summary": "Delete environment", "description": "Deletes an environment and all its secrets. Cannot delete default environments (development, staging, production).", "operationId": "deleteEnvironment", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" } ], "responses": { "204": { "description": "Environment deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/secrets": { "get": { "tags": [ "Secrets" ], "summary": "List secrets", "description": "Returns all secrets in an environment (keys and metadata only, no values). Includes inherited secrets from parent environments.", "operationId": "listSecrets", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" } ], "responses": { "200": { "description": "List of secrets", "content": { "application/json": { "schema": { "type": "object", "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretWithInheritance" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "post": { "tags": [ "Secrets" ], "summary": "Create secret", "description": "Creates a new secret in an environment", "operationId": "createSecret", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSecretRequest" } } } }, "responses": { "201": { "description": "Secret created", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "$ref": "#/components/schemas/Secret" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/LimitExceeded" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/secrets/export": { "get": { "tags": [ "Secrets" ], "summary": "Export secrets", "description": "Exports all secrets with their decrypted values. Use this for CI/CD or local development.\nIncludes inherited secrets from parent environments.\n\n**Note:** This endpoint logs an audit event for compliance.\n", "operationId": "exportSecrets", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" } ], "responses": { "200": { "description": "Secrets with values", "content": { "application/json": { "schema": { "type": "object", "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/SecretWithValueAndInheritance" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/secrets/bulk": { "post": { "tags": [ "Secrets" ], "summary": "Bulk import secrets", "description": "Imports multiple secrets at once. Useful for migrating from .env files or other systems.\n\n- Maximum 100 secrets per request\n- Set `overwrite: true` to update existing secrets\n- Set `overwrite: false` to skip existing secrets\n", "operationId": "bulkImportSecrets", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportRequest" } } } }, "responses": { "200": { "description": "Import results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkImportResult" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/LimitExceeded" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}": { "get": { "tags": [ "Secrets" ], "summary": "Get secret", "description": "Returns a single secret with its decrypted value", "operationId": "getSecret", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/secretKey" } ], "responses": { "200": { "description": "Secret with value", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "$ref": "#/components/schemas/SecretWithValue" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Secrets" ], "summary": "Update secret", "description": "Updates a secret's value and/or description. Previous values are preserved in history.", "operationId": "updateSecret", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/secretKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSecretRequest" } } } }, "responses": { "200": { "description": "Secret updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "secret": { "$ref": "#/components/schemas/Secret" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Secrets" ], "summary": "Delete secret", "description": "Permanently deletes a secret", "operationId": "deleteSecret", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/secretKey" } ], "responses": { "204": { "description": "Secret deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/secrets/{key}/history": { "get": { "tags": [ "Secrets" ], "summary": "Get secret history", "description": "Returns the version history of a secret with decrypted values", "operationId": "getSecretHistory", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/secretKey" } ], "responses": { "200": { "description": "Secret history", "content": { "application/json": { "schema": { "type": "object", "properties": { "history": { "type": "array", "items": { "$ref": "#/components/schemas/SecretHistory" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/projects/{projectId}/my-permissions": { "get": { "tags": [ "Permissions" ], "summary": "Get my permissions", "description": "Returns the current user's permissions for all environments in a project", "operationId": "getMyPermissions", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" } ], "responses": { "200": { "description": "User permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MyPermissionsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/permissions": { "get": { "tags": [ "Permissions" ], "summary": "List environment permissions", "description": "Lists all user permissions for an environment", "operationId": "listEnvironmentPermissions", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" } ], "responses": { "200": { "description": "List of permissions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/EnvironmentPermission" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "put": { "tags": [ "Permissions" ], "summary": "Bulk set permissions", "description": "Sets permissions for multiple users at once", "operationId": "bulkSetPermissions", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSetPermissionsRequest" } } } }, "responses": { "200": { "description": "Permissions updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/permissions/{userId}": { "get": { "tags": [ "Permissions" ], "summary": "Get user permission", "description": "Returns a specific user's permission for an environment", "operationId": "getUserPermission", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "200": { "description": "User permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentPermission" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Permissions" ], "summary": "Set user permission", "description": "Sets a user's permission for an environment", "operationId": "setUserPermission", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/userId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetPermissionRequest" } } } }, "responses": { "200": { "description": "Permission set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvironmentPermission" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "tags": [ "Permissions" ], "summary": "Delete user permission", "description": "Removes a user's explicit permission for an environment", "operationId": "deleteUserPermission", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/userId" } ], "responses": { "204": { "description": "Permission deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/permissions/defaults": { "get": { "tags": [ "Permissions" ], "summary": "Get default permissions", "description": "Returns default permissions for new team members in a project", "operationId": "getDefaultPermissions", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" } ], "responses": { "200": { "description": "Default permissions", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectDefaultPermission" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "put": { "tags": [ "Permissions" ], "summary": "Set default permissions", "description": "Sets default permissions for new team members", "operationId": "setDefaultPermissions", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetDefaultPermissionsRequest" } } } }, "responses": { "200": { "description": "Defaults updated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/rotations": { "get": { "tags": [ "Rotations" ], "summary": "List rotations", "description": "Lists all rotation configurations for an environment", "operationId": "listRotations", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" } ], "responses": { "200": { "description": "List of rotations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotationConfigListResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Rotations" ], "summary": "Create rotation", "description": "Creates a new automated credential rotation configuration", "operationId": "createRotation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRotationRequest" } } } }, "responses": { "201": { "description": "Rotation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotationConfigResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/rotations/test": { "post": { "tags": [ "Rotations" ], "summary": "Test connection", "description": "Tests database connection without saving the rotation config", "operationId": "testRotationConnection", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestConnectionRequest" } } } }, "responses": { "200": { "description": "Connection test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}": { "get": { "tags": [ "Rotations" ], "summary": "Get rotation", "description": "Returns a rotation configuration by name", "operationId": "getRotation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/rotationName" } ], "responses": { "200": { "description": "Rotation details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotationConfigResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Rotations" ], "summary": "Update rotation", "description": "Updates rotation interval or status", "operationId": "updateRotation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/rotationName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRotationRequest" } } } }, "responses": { "200": { "description": "Rotation updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotationConfigResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "tags": [ "Rotations" ], "summary": "Delete rotation", "description": "Deletes a rotation configuration", "operationId": "deleteRotation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/rotationName" } ], "responses": { "204": { "description": "Rotation deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/rotate": { "post": { "tags": [ "Rotations" ], "summary": "Trigger rotation", "description": "Manually triggers a credential rotation", "operationId": "triggerRotation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/rotationName" } ], "responses": { "200": { "description": "Rotation triggered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotationHistory" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/test": { "post": { "tags": [ "Rotations" ], "summary": "Test existing rotation", "description": "Tests database connection for an existing rotation", "operationId": "testExistingRotation", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/rotationName" } ], "responses": { "200": { "description": "Test result", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/history": { "get": { "tags": [ "Rotations" ], "summary": "Get rotation history", "description": "Returns rotation execution history", "operationId": "getRotationHistory", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/rotationName" } ], "responses": { "200": { "description": "Rotation history", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RotationHistory" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks": { "get": { "tags": [ "Rotations" ], "summary": "List rotation webhooks", "description": "Lists webhooks for a rotation configuration", "operationId": "listRotationWebhooks", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/rotationName" } ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/RotationWebhook" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Rotations" ], "summary": "Create rotation webhook", "description": "Creates a webhook for rotation events", "operationId": "createRotationWebhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/rotationName" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" } } } }, "responses": { "201": { "description": "Webhook created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotationWebhook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/environments/{environmentId}/rotations/{rotationName}/webhooks/{webhookId}": { "delete": { "tags": [ "Rotations" ], "summary": "Delete rotation webhook", "description": "Deletes a rotation webhook", "operationId": "deleteRotationWebhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "$ref": "#/components/parameters/environmentId" }, { "$ref": "#/components/parameters/rotationName" }, { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "description": "Webhook deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/scans": { "get": { "tags": [ "Scans" ], "summary": "List scans", "description": "Lists secret scan results for a project", "operationId": "listScans", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" } ], "responses": { "200": { "description": "List of scans", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Scan" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Scans" ], "summary": "Upload scan results", "description": "Uploads secret scan results from CLI or GitHub Action", "operationId": "uploadScan", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadScanRequest" } } } }, "responses": { "201": { "description": "Scan uploaded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadScanResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/projects/{projectId}/scans/{scanId}": { "get": { "tags": [ "Scans" ], "summary": "Get scan", "description": "Returns a scan with its findings", "operationId": "getScan", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "name": "scanId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Scan details with findings", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanWithFindings" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/projects/{projectId}/scans/{scanId}/findings/{findingId}": { "patch": { "tags": [ "Scans" ], "summary": "Update finding status", "description": "Updates a scan finding status (dismiss or reactivate)", "operationId": "updateFindingStatus", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/projectId" }, { "name": "scanId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "findingId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "active", "dismissed", "fixed" ] }, "dismissed_reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Finding updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanFinding" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/tokens": { "get": { "tags": [ "Tokens" ], "summary": "List service tokens", "description": "Returns all service tokens created by the user", "operationId": "listTokens", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of tokens", "content": { "application/json": { "schema": { "type": "object", "properties": { "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/ServiceToken" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "Tokens" ], "summary": "Create service token", "description": "Creates a new service token for CI/CD or programmatic access.\n\n**Important:** The token value is only returned once upon creation. Store it securely.\n", "operationId": "createToken", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTokenRequest" } } } }, "responses": { "201": { "description": "Token created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceTokenWithValue" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/tokens/{tokenId}": { "delete": { "tags": [ "Tokens" ], "summary": "Delete service token", "description": "Permanently revokes a service token", "operationId": "deleteToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/tokenId" } ], "responses": { "204": { "description": "Token deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/tokens/{tokenId}/rotate": { "post": { "tags": [ "Tokens" ], "summary": "Rotate service token", "description": "Rotates a service token, creating a new one with an optional grace period\nduring which the old token remains valid. This allows seamless token rotation\nin CI/CD systems.\n", "operationId": "rotateToken", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/tokenId" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateTokenRequest" } } } }, "responses": { "200": { "description": "Token rotated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateTokenResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/audit": { "get": { "tags": [ "Audit" ], "summary": "List audit logs", "description": "Returns audit logs for teams the user has access to", "operationId": "listAuditLogs", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "team_id", "in": "query", "description": "Filter by team ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "description": "Maximum number of results", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of results to skip", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Audit logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/teams/{teamId}/audit": { "get": { "tags": [ "Audit" ], "summary": "List team audit logs", "description": "Returns audit logs for a specific team", "operationId": "listTeamAuditLogs", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" }, { "name": "limit", "in": "query", "description": "Maximum number of results", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "offset", "in": "query", "description": "Number of results to skip", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "Audit logs", "content": { "application/json": { "schema": { "type": "object", "properties": { "logs": { "type": "array", "items": { "$ref": "#/components/schemas/AuditLog" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/teams/{teamId}/usage": { "get": { "tags": [ "Billing" ], "summary": "Get team usage", "description": "Returns current usage statistics for a team", "operationId": "getTeamUsage", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "responses": { "200": { "description": "Usage statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageStats" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/teams/{teamId}/limits": { "get": { "tags": [ "Billing" ], "summary": "Get team limits", "description": "Returns plan limits for a team", "operationId": "getTeamLimits", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "responses": { "200": { "description": "Plan limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanLimits" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/teams/{teamId}/billing": { "get": { "tags": [ "Billing" ], "summary": "Get billing info", "description": "Returns billing information including current plan and subscription status", "operationId": "getTeamBilling", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "responses": { "200": { "description": "Billing information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingInfo" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/teams/{teamId}/checkout": { "post": { "tags": [ "Billing" ], "summary": "Create checkout session", "description": "Creates a Stripe checkout session for upgrading the team's plan", "operationId": "createCheckoutSession", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutRequest" } } } }, "responses": { "200": { "description": "Checkout session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL to redirect the user to for checkout" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/teams/{teamId}/portal": { "post": { "tags": [ "Billing" ], "summary": "Create billing portal session", "description": "Creates a Stripe billing portal session for managing subscription", "operationId": "createPortalSession", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/teamId" } ], "responses": { "200": { "description": "Portal session created", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "URL to redirect the user to for the billing portal" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/api/v1/cli/login": { "post": { "tags": [ "CLI" ], "summary": "Initiate CLI login", "description": "Initiates the CLI login flow, returns a URL to open in the browser", "operationId": "cliLogin", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CLILoginRequest" } } } }, "responses": { "200": { "description": "Login URL generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CLILoginResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/cli/callback": { "post": { "tags": [ "CLI" ], "summary": "Complete CLI login", "description": "Called by the web app after browser authentication completes", "operationId": "cliCallback", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CLICallbackRequest" } } } }, "responses": { "200": { "description": "Login completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CLICallbackResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/cli/status": { "get": { "tags": [ "CLI" ], "summary": "Poll CLI login status", "description": "Polls the status of a CLI login flow", "operationId": "cliStatus", "security": [], "parameters": [ { "name": "state", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Login status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CLIStatusResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/cli/refresh": { "post": { "tags": [ "CLI" ], "summary": "Refresh CLI token", "description": "Refreshes an expired access token using a refresh token", "operationId": "cliRefresh", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CLIRefreshRequest" } } } }, "responses": { "200": { "description": "New access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CLIRefreshResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/cli/logout": { "post": { "tags": [ "CLI" ], "summary": "CLI logout", "description": "Revokes the CLI session", "operationId": "cliLogout", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CLILogoutRequest" } } } }, "responses": { "200": { "description": "Logged out" }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/api/v1/cli/whoami": { "get": { "tags": [ "CLI" ], "summary": "CLI whoami", "description": "Returns the current user and session info", "operationId": "cliWhoami", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "User and session info", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CLIWhoamiResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/account/data-export": { "get": { "tags": [ "Account" ], "summary": "Get data export status", "description": "Returns the status of a pending data export request", "operationId": "getDataExportStatus", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Export status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataExportStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/account/data-export/request": { "post": { "tags": [ "Account" ], "summary": "Request data export", "description": "Requests a GDPR data export", "operationId": "requestDataExport", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Export requested", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DataExportRequestResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/account/data-export/download": { "get": { "tags": [ "Account" ], "summary": "Download data export", "description": "Downloads the completed data export", "operationId": "downloadDataExport", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Export data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDataExport" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/account": { "delete": { "tags": [ "Account" ], "summary": "Delete account", "description": "Permanently deletes the user account and all associated data", "operationId": "deleteAccount", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccountRequest" } } } }, "responses": { "200": { "description": "Account deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAccountResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/eso/secret": { "get": { "tags": [ "ESO" ], "summary": "Get single secret for ESO", "description": "Fetches a single secret value for External Secrets Operator webhook integration.\n\nThis endpoint is designed for ESO's webhook provider to fetch individual secrets.\nThe environment can be specified by name or ID.\n\n**Authentication:** Only service token authentication is supported. User authentication\nwill return 403 Forbidden.\n\n**Environment Inheritance:** If the secret is not found in the specified environment,\nthe inheritance chain is searched (child environments inherit from parents).\n", "operationId": "getESOSecret", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project", "in": "query", "required": true, "description": "Project ID or slug", "schema": { "type": "string" }, "example": "proj_abc123" }, { "name": "env", "in": "query", "required": true, "description": "Environment name or ID", "schema": { "type": "string" }, "example": "production" }, { "name": "key", "in": "query", "required": true, "description": "Secret key name", "schema": { "type": "string" }, "example": "DATABASE_URL" } ], "responses": { "200": { "description": "Secret value retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ESOSecretResponse" } } } }, "400": { "description": "Bad request. Possible causes:\n- Missing required query parameters (project, env, key)\n- Circular environment inheritance detected\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Possible causes:\n- Service token does not have access to this project\n- User authentication was used (ESO requires service token)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Possible causes:\n- Project not found\n- Environment not found\n- Secret not found (including in inherited environments)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error (e.g., decryption failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/eso/secrets": { "get": { "tags": [ "ESO" ], "summary": "Get all secrets for ESO dataFrom", "description": "Fetches all secrets as a key-value map for External Secrets Operator's `dataFrom` feature.\n\nThis endpoint is designed for ESO's webhook provider to bulk-fetch all secrets from\nan environment. The environment can be specified by name or ID.\n\n**Authentication:** Only service token authentication is supported. User authentication\nwill return 403 Forbidden.\n\n**Environment Inheritance:** Secrets are resolved through the inheritance chain.\nChild environment values override parent values for the same key.\n\n**Hidden Secrets:** Secrets that have been explicitly hidden (overridden with no value)\nin the target environment are excluded from the response.\n", "operationId": "getESOSecrets", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "project", "in": "query", "required": true, "description": "Project ID or slug", "schema": { "type": "string" }, "example": "proj_abc123" }, { "name": "env", "in": "query", "required": true, "description": "Environment name or ID", "schema": { "type": "string" }, "example": "production" } ], "responses": { "200": { "description": "All secrets retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ESOSecretsResponse" } } } }, "400": { "description": "Bad request. Possible causes:\n- Missing required query parameters (project, env)\n- Circular environment inheritance detected\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required or invalid token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Forbidden. Possible causes:\n- Service token does not have access to this project\n- User authentication was used (ESO requires service token)\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found. Possible causes:\n- Project not found\n- Environment not found\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal server error (e.g., decryption failure)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Clerk JWT token or KeyEnv service token" } }, "parameters": { "teamId": { "name": "teamId", "in": "path", "required": true, "description": "Team UUID", "schema": { "type": "string", "format": "uuid" } }, "userId": { "name": "userId", "in": "path", "required": true, "description": "User UUID", "schema": { "type": "string", "format": "uuid" } }, "projectId": { "name": "projectId", "in": "path", "required": true, "description": "Project UUID or slug (e.g., \"my-project\")", "schema": { "type": "string" } }, "environmentId": { "name": "environmentId", "in": "path", "required": true, "description": "Environment UUID or name (e.g., \"development\", \"staging\", \"production\")", "schema": { "type": "string" } }, "secretKey": { "name": "key", "in": "path", "required": true, "description": "Secret key (uppercase letters, numbers, underscores)", "schema": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "example": "DATABASE_URL" } }, "tokenId": { "name": "tokenId", "in": "path", "required": true, "description": "Service token UUID", "schema": { "type": "string", "format": "uuid" } }, "rotationName": { "name": "rotationName", "in": "path", "required": true, "description": "Rotation configuration name", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Authentication required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Resource already exists", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "LimitExceeded": { "description": "Plan limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitError" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Error message", "example": "Invalid request" } } }, "LimitError": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Error message" }, "code": { "type": "string", "enum": [ "limit_exceeded" ] }, "details": { "type": "object", "properties": { "current": { "type": "integer" }, "limit": { "type": "integer" }, "resource": { "type": "string" } } } } }, "HealthResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "service": { "type": "string", "example": "keyenv-api" }, "version": { "type": "string" }, "build_time": { "type": "string" }, "checks": { "type": "object", "additionalProperties": { "type": "string" } } } }, "User": { "type": "object", "description": "User profile or service token info. For service tokens, includes project_ids and scopes.", "properties": { "id": { "type": "string", "format": "uuid" }, "clerk_id": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "avatar_url": { "type": "string", "format": "uri" }, "auth_type": { "type": "string", "enum": [ "user", "service_token" ], "description": "Authentication type. Only present for service token auth." }, "team_id": { "type": "string", "format": "uuid", "description": "Team ID. Only present for service token auth." }, "project_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Project IDs the token has access to. Only present for service token auth. Tokens can access multiple projects." }, "scopes": { "type": "array", "items": { "type": "string" }, "description": "Token scopes (e.g., read, write). Only present for service token auth." }, "created_at": { "type": "string", "format": "date-time" } } }, "Team": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "plan": { "type": "string", "enum": [ "free", "team", "enterprise" ] }, "is_personal": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "TeamMember": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "avatar_url": { "type": "string", "format": "uri" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] }, "joined_at": { "type": "string", "format": "date-time" } } }, "TeamWithMembers": { "allOf": [ { "$ref": "#/components/schemas/Team" }, { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMember" } } } } ] }, "CreateTeamRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "InviteMemberRequest": { "type": "object", "required": [ "email", "role" ], "properties": { "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "admin", "developer", "viewer" ] } } }, "UpdateMemberRoleRequest": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "admin", "developer", "viewer" ] } } }, "Project": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "team_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "Environment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "inherits_from": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "ProjectWithEnvironments": { "allOf": [ { "$ref": "#/components/schemas/Project" }, { "type": "object", "properties": { "environments": { "type": "array", "items": { "$ref": "#/components/schemas/Environment" } } } } ] }, "CreateProjectRequest": { "type": "object", "required": [ "team_id", "name" ], "properties": { "team_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "UpdateProjectRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "CreateEnvironmentRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "inherits_from": { "type": "string", "format": "uuid", "description": "Parent environment ID for secret inheritance" } } }, "Secret": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "environment_id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" }, "description": { "type": "string", "nullable": true }, "version": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "SecretWithValue": { "allOf": [ { "$ref": "#/components/schemas/Secret" }, { "type": "object", "properties": { "value": { "type": "string" } } } ] }, "SecretWithInheritance": { "allOf": [ { "$ref": "#/components/schemas/Secret" }, { "type": "object", "properties": { "inherited_from": { "type": "string", "nullable": true, "description": "Environment name if secret is inherited" } } } ] }, "SecretWithValueAndInheritance": { "allOf": [ { "$ref": "#/components/schemas/SecretWithValue" }, { "type": "object", "properties": { "inherited_from": { "type": "string", "nullable": true } } } ] }, "SecretHistory": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "secret_id": { "type": "string", "format": "uuid" }, "value": { "type": "string" }, "version": { "type": "integer" }, "changed_by": { "type": "string", "format": "uuid", "nullable": true }, "changed_at": { "type": "string", "format": "date-time" } } }, "CreateSecretRequest": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$", "maxLength": 255, "description": "Must be uppercase letters, numbers, and underscores, starting with a letter", "example": "DATABASE_URL" }, "value": { "type": "string", "minLength": 1 }, "description": { "type": "string", "maxLength": 500 } } }, "UpdateSecretRequest": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "string", "minLength": 1 }, "description": { "type": "string", "maxLength": 500 } } }, "BulkSecretItem": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]*$" }, "value": { "type": "string" }, "description": { "type": "string" } } }, "BulkImportRequest": { "type": "object", "required": [ "secrets" ], "properties": { "secrets": { "type": "array", "items": { "$ref": "#/components/schemas/BulkSecretItem" }, "minItems": 1, "maxItems": 100 }, "overwrite": { "type": "boolean", "default": false, "description": "Whether to overwrite existing secrets" } } }, "BulkImportResult": { "type": "object", "properties": { "created": { "type": "integer", "description": "Number of secrets created" }, "updated": { "type": "integer", "description": "Number of secrets updated (when overwrite=true)" }, "skipped": { "type": "integer", "description": "Number of secrets skipped (existing, when overwrite=false)" } } }, "ServiceToken": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "team_id": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "write" ] } }, "last_used_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "ServiceTokenWithValue": { "allOf": [ { "$ref": "#/components/schemas/ServiceToken" }, { "type": "object", "properties": { "token": { "type": "string", "description": "The token value (only shown once)" } } } ] }, "CreateTokenRequest": { "type": "object", "required": [ "name", "team_id", "scopes" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "team_id": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "write" ] }, "minItems": 1 }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Optional expiration date" } } }, "AuditLog": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "team_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid", "nullable": true }, "action": { "type": "string", "enum": [ "secret.created", "secret.read", "secret.updated", "secret.deleted", "project.created", "project.updated", "project.deleted", "environment.created", "environment.deleted", "team.member_invited", "team.member_removed", "team.member_role_changed", "token.created", "token.deleted" ] }, "resource_id": { "type": "string" }, "ip_address": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "UsageStats": { "type": "object", "properties": { "projects": { "type": "integer" }, "environments": { "type": "integer" }, "secrets": { "type": "integer" }, "members": { "type": "integer" } } }, "PlanLimits": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "free", "team", "enterprise" ] }, "projects": { "type": "integer", "description": "Maximum number of projects (-1 for unlimited)" }, "environments_per_project": { "type": "integer" }, "secrets_per_environment": { "type": "integer" }, "members": { "type": "integer" } } }, "BillingInfo": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "free", "team", "enterprise" ] }, "status": { "type": "string", "enum": [ "active", "canceled", "past_due", "trialing" ] }, "current_period_end": { "type": "string", "format": "date-time", "nullable": true }, "cancel_at_period_end": { "type": "boolean" } } }, "CreateCheckoutRequest": { "type": "object", "required": [ "plan" ], "properties": { "plan": { "type": "string", "enum": [ "team", "enterprise" ] }, "success_url": { "type": "string", "format": "uri" }, "cancel_url": { "type": "string", "format": "uri" } } }, "ESOSecretResponse": { "type": "object", "description": "ESO-compatible single secret response", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "The decrypted secret value", "example": "postgres://user:pass@localhost:5432/db" } } }, "ESOSecretsResponse": { "type": "object", "description": "ESO-compatible bulk secrets response for dataFrom", "required": [ "secrets" ], "properties": { "secrets": { "type": "object", "description": "Key-value map of all secrets in the environment", "additionalProperties": { "type": "string" }, "example": { "DATABASE_URL": "postgres://user:pass@localhost:5432/db", "API_KEY": "sk_live_abc123", "REDIS_URL": "redis://localhost:6379" } } } }, "TeamInvitation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "team_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "invited_by": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "InvitationPublicInfo": { "type": "object", "properties": { "team_name": { "type": "string" }, "invited_by_email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "admin", "member" ] }, "email": { "type": "string", "format": "email" }, "expires_at": { "type": "string", "format": "date-time" }, "token": { "type": "string" } } }, "EnvironmentPermission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "environment_id": { "type": "string", "format": "uuid" }, "user_id": { "type": "string", "format": "uuid" }, "user_email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "none", "read", "write", "admin" ] }, "granted_by": { "type": "string", "format": "uuid", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MyPermissionsResponse": { "type": "object", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "environment_id": { "type": "string", "format": "uuid" }, "environment_name": { "type": "string" }, "role": { "type": "string", "enum": [ "none", "read", "write", "admin" ] }, "can_read": { "type": "boolean" }, "can_write": { "type": "boolean" }, "can_admin": { "type": "boolean" } } } }, "is_team_admin": { "type": "boolean" } } }, "SetPermissionRequest": { "type": "object", "required": [ "role" ], "properties": { "role": { "type": "string", "enum": [ "none", "read", "write", "admin" ] } } }, "BulkSetPermissionsRequest": { "type": "object", "required": [ "permissions" ], "properties": { "permissions": { "type": "array", "items": { "type": "object", "required": [ "user_id", "role" ], "properties": { "user_id": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "none", "read", "write", "admin" ] } } } } } }, "ProjectDefaultPermission": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "environment_name": { "type": "string", "description": "Environment name or \"*\" for all" }, "default_role": { "type": "string", "enum": [ "none", "read", "write", "admin" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "SetDefaultPermissionsRequest": { "type": "object", "required": [ "defaults" ], "properties": { "defaults": { "type": "array", "items": { "type": "object", "required": [ "environment_name", "default_role" ], "properties": { "environment_name": { "type": "string" }, "default_role": { "type": "string", "enum": [ "none", "read", "write", "admin" ] } } } } } }, "RotateTokenRequest": { "type": "object", "properties": { "grace_period_minutes": { "type": "integer", "minimum": 0, "default": 5, "description": "How long the old token remains valid" } } }, "RotateTokenResponse": { "type": "object", "properties": { "new_token": { "$ref": "#/components/schemas/ServiceTokenWithValue" }, "old_token_expires_at": { "type": "string", "format": "date-time" } } }, "RotationConfigListResponse": { "type": "object", "properties": { "rotations": { "type": "array", "items": { "$ref": "#/components/schemas/RotationConfigResponse" } } } }, "RotationConfigResponse": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "environment_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "integration_type": { "type": "string", "enum": [ "postgresql", "mysql" ] }, "rotation_interval_days": { "type": "integer" }, "connection_method": { "type": "string", "enum": [ "direct", "proxied" ] }, "status": { "type": "string", "enum": [ "active", "paused", "disabled", "error" ] }, "last_rotation_at": { "type": "string", "format": "date-time", "nullable": true }, "next_rotation_at": { "type": "string", "format": "date-time", "nullable": true }, "error_message": { "type": "string", "nullable": true }, "injected_secrets": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "CreateRotationRequest": { "type": "object", "required": [ "name", "integration_type", "connection_method", "connection", "rotation_interval_days" ], "properties": { "name": { "type": "string", "maxLength": 100 }, "integration_type": { "type": "string", "enum": [ "postgresql", "mysql" ] }, "connection_method": { "type": "string", "enum": [ "direct", "proxied" ] }, "connection": { "type": "object", "required": [ "host", "port", "database", "admin_username", "admin_password" ], "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "database": { "type": "string" }, "admin_username": { "type": "string" }, "admin_password": { "type": "string" }, "ssl_mode": { "type": "string" } } }, "proxy": { "type": "object", "properties": { "lambda_arn": { "type": "string" }, "region": { "type": "string" }, "shared_secret": { "type": "string" } } }, "rotation_interval_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "permission_level": { "type": "string" } } }, "UpdateRotationRequest": { "type": "object", "properties": { "rotation_interval_days": { "type": "integer", "minimum": 1, "maximum": 365 }, "status": { "type": "string", "enum": [ "active", "paused" ] } } }, "TestConnectionRequest": { "type": "object", "required": [ "integration_type", "connection_method", "connection" ], "properties": { "integration_type": { "type": "string", "enum": [ "postgresql", "mysql" ] }, "connection_method": { "type": "string", "enum": [ "direct", "proxied" ] }, "connection": { "type": "object", "required": [ "host", "port", "database", "admin_username", "admin_password" ], "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "database": { "type": "string" }, "admin_username": { "type": "string" }, "admin_password": { "type": "string" }, "ssl_mode": { "type": "string" } } }, "proxy": { "type": "object", "properties": { "lambda_arn": { "type": "string" }, "region": { "type": "string" }, "shared_secret": { "type": "string" } } } } }, "RotationHistory": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "rotation_config_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer" }, "triggered_by": { "type": "string", "format": "uuid", "nullable": true }, "trigger_type": { "type": "string", "enum": [ "scheduled", "manual" ] }, "status": { "type": "string", "enum": [ "success", "failed", "rolled_back" ] }, "started_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "error_message": { "type": "string", "nullable": true } } }, "RotationWebhook": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "rotation_config_id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "rotation.started", "rotation.completed", "rotation.failed" ] } }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "CreateWebhookRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "rotation.started", "rotation.completed", "rotation.failed" ] } } } }, "Scan": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "source": { "type": "string", "enum": [ "cli", "action", "app" ] }, "commit_sha": { "type": "string", "nullable": true }, "branch": { "type": "string", "nullable": true }, "findings_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "type": "string", "format": "uuid", "nullable": true } } }, "ScanFinding": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "scan_id": { "type": "string", "format": "uuid" }, "pattern_id": { "type": "string" }, "pattern_name": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "file_path": { "type": "string" }, "line_number": { "type": "integer" }, "snippet": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "dismissed", "fixed" ] }, "dismissed_by": { "type": "string", "format": "uuid", "nullable": true }, "dismissed_at": { "type": "string", "format": "date-time", "nullable": true }, "dismissed_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "ScanWithFindings": { "allOf": [ { "$ref": "#/components/schemas/Scan" }, { "type": "object", "properties": { "findings": { "type": "array", "items": { "$ref": "#/components/schemas/ScanFinding" } } } } ] }, "UploadScanRequest": { "type": "object", "properties": { "findings": { "type": "array", "items": { "type": "object", "required": [ "pattern_id", "severity", "file_path", "line_number" ], "properties": { "pattern_id": { "type": "string" }, "pattern_name": { "type": "string" }, "severity": { "type": "string", "enum": [ "critical", "high", "medium", "low" ] }, "file_path": { "type": "string" }, "line_number": { "type": "integer" }, "matched_text": { "type": "string" } } } }, "source": { "type": "string", "enum": [ "cli", "action", "app" ], "default": "cli" }, "commit_sha": { "type": "string" }, "branch": { "type": "string" } } }, "UploadScanResponse": { "type": "object", "properties": { "scan_id": { "type": "string", "format": "uuid" }, "findings_count": { "type": "integer" } } }, "CLILoginRequest": { "type": "object", "required": [ "redirect_uri" ], "properties": { "redirect_uri": { "type": "string", "format": "uri" }, "device_name": { "type": "string" } } }, "CLILoginResponse": { "type": "object", "properties": { "auth_url": { "type": "string", "format": "uri" }, "state": { "type": "string" }, "expires_in": { "type": "integer", "description": "Seconds until state expires" }, "user_code": { "type": "string", "pattern": "^[0-9A-F]{4}-[0-9A-F]{4}$", "example": "6CA1-3D52", "description": "Verification code derived from the state (first 8 uppercase hex chars of SHA-256(state), formatted XXXX-XXXX). The CLI displays it and the browser consent screen shows the same code so the user can confirm they match." } } }, "CLICallbackRequest": { "type": "object", "required": [ "state" ], "properties": { "state": { "type": "string" } } }, "CLICallbackResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" } } } } }, "CLIStatusResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "completed", "expired" ] }, "refresh_token": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "expires_at": { "type": "string", "format": "date-time" } } }, "CLIRefreshRequest": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string" } } }, "CLIRefreshResponse": { "type": "object", "properties": { "access_token": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } } }, "CLILogoutRequest": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string" } } }, "CLIWhoamiResponse": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" } } } }, "session_created_at": { "type": "string", "format": "date-time" } } }, "DataExportStatusResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "none", "pending", "ready", "expired" ] }, "requested_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true } } }, "DataExportRequestResponse": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" } } }, "DeleteAccountRequest": { "type": "object", "required": [ "confirmation" ], "properties": { "confirmation": { "type": "string", "description": "Must be \"DELETE\"" } } }, "DeleteAccountResponse": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "UserDataExport": { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } }, "teams": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "role": { "type": "string" }, "plan": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "projects": { "type": "array", "items": { "type": "object" } }, "audit_logs": { "type": "array", "items": { "type": "object" } } } } }, "exported_at": { "type": "string", "format": "date-time" } } } } } }