diff --git a/go/apps/api/openapi/spec/common/identity.yaml b/go/apps/api/openapi/spec/common/identity.yaml deleted file mode 100644 index cdf01d9d41..0000000000 --- a/go/apps/api/openapi/spec/common/identity.yaml +++ /dev/null @@ -1,16 +0,0 @@ -type: object -properties: - externalId: - type: string - description: External identity ID - meta: - type: object - description: Identity metadata - ratelimits: - type: array - items: - "$ref": "./RatelimitResponse.yaml" - description: Identity ratelimits -required: - - externalId - - ratelimits diff --git a/go/apps/api/openapi/spec/common/keyCreditsRefill.yaml b/go/apps/api/openapi/spec/common/keyCreditsRefill.yaml deleted file mode 100644 index 2170cdf55a..0000000000 --- a/go/apps/api/openapi/spec/common/keyCreditsRefill.yaml +++ /dev/null @@ -1,30 +0,0 @@ -type: object -description: Configuration for automatic credit refill behavior. -properties: - interval: - type: string - enum: - - daily - - monthly - description: How often credits are automatically refilled. - example: daily - amount: - type: integer - format: int64 - minimum: 1 - maximum: 9223372036854775807 - description: Number of credits to add during each refill cycle. - example: 1000 - refillDay: - type: integer - minimum: 1 - maximum: 31 - description: | - Day of the month for monthly refills (1-31). - Only required when interval is 'monthly'. - For days beyond the month's length, refill occurs on the last day of the month. - example: 15 -required: - - interval - - amount -additionalProperties: false diff --git a/go/apps/api/openapi/spec/common/meta.yaml b/go/apps/api/openapi/spec/common/meta.yaml deleted file mode 100644 index c3b46a9cdc..0000000000 --- a/go/apps/api/openapi/spec/common/meta.yaml +++ /dev/null @@ -1,18 +0,0 @@ -type: object -required: - - requestId -properties: - requestId: - description: - A unique id for this request. Always include this ID when contacting - support about a specific API request. This identifier allows Unkey's support - team to trace the exact request through logs and diagnostic systems to - provide faster assistance. - example: req_123 - type: string -additionalProperties: false -description: - Metadata object included in every API response. This provides context - about the request and is essential for debugging, audit trails, and support - inquiries. The `requestId` is particularly important when troubleshooting issues - with the Unkey support team. diff --git a/go/apps/api/openapi/spec/common/pagination.yaml b/go/apps/api/openapi/spec/common/pagination.yaml deleted file mode 100644 index d6e82dd5c4..0000000000 --- a/go/apps/api/openapi/spec/common/pagination.yaml +++ /dev/null @@ -1,24 +0,0 @@ -type: object -properties: - cursor: - type: string - minLength: 1 - maxLength: 1024 # Reasonable upper bound for cursor tokens - description: | - Opaque pagination token for retrieving the next page of results. - Include this exact value in the cursor field of subsequent requests. - Cursors are temporary and may expire after extended periods. - example: eyJrZXkiOiJrZXlfMTIzNCIsInRzIjoxNjk5Mzc4ODAwfQ== - hasMore: - type: boolean - description: | - Indicates whether additional results exist beyond this page. - When true, use the cursor to fetch the next page. - When false, you have reached the end of the result set. - example: true -required: - - hasMore -additionalProperties: false -description: - Pagination metadata for list endpoints. Provides information necessary - to traverse through large result sets efficiently using cursor-based pagination. diff --git a/go/apps/api/openapi/spec/common/permission.yaml b/go/apps/api/openapi/spec/common/permission.yaml deleted file mode 100644 index e315734956..0000000000 --- a/go/apps/api/openapi/spec/common/permission.yaml +++ /dev/null @@ -1,42 +0,0 @@ -type: object -properties: - id: - type: string - minLength: 3 - maxLength: 255 - pattern: "^[a-zA-Z0-9_]+$" - description: | - The unique identifier for this permission within Unkey's system. - Generated automatically when the permission is created and used to reference this permission in API operations. - Always begins with 'perm_' followed by alphanumeric characters and underscores. - example: perm_1234567890abcdef - name: - type: string - minLength: 1 - maxLength: 512 - description: | - The human-readable name for this permission that describes its purpose. - Should be descriptive enough for developers to understand what access it grants. - Use clear, semantic names that reflect the resources or actions being permitted. - Names must be unique within your workspace to avoid confusion and conflicts. - example: "users.read" - slug: - pattern: ^[a-zA-Z0-9_:\-\.\*]+$ - type: string - minLength: 1 - maxLength: 512 - description: The URL-safe identifier when this permission was created. - example: users-read - description: - type: string - maxLength: 2048 - description: | - Optional detailed explanation of what this permission grants access to. - Helps team members understand the scope and implications of granting this permission. - Include information about what resources can be accessed and what actions can be performed. - Not visible to end users - this is for internal documentation and team clarity. - example: "Allows reading user profile information and account details" -required: - - id - - name - - slug diff --git a/go/apps/api/openapi/spec/common/ratelimitOverride.yaml b/go/apps/api/openapi/spec/common/ratelimitOverride.yaml deleted file mode 100644 index c51ad1e63e..0000000000 --- a/go/apps/api/openapi/spec/common/ratelimitOverride.yaml +++ /dev/null @@ -1,52 +0,0 @@ -type: object -additionalProperties: false -properties: - overrideId: - description: The unique identifier of this specific rate limit override. - This ID is generated when the override is created and can be used for - management operations like updating or deleting the override. - type: string - minLength: 1 - maxLength: 255 - duration: - description: The duration in milliseconds for this override's rate limit - window. This may differ from the default duration for the namespace, allowing - custom time windows for specific entities. After this duration elapses, - the rate limit counter for affected identifiers resets to zero. - format: int64 - type: integer - minimum: 1000 - identifier: - description: |- - The identifier pattern this override applies to. This determines which entities receive the custom rate limit. - - This can be: - - An exact identifier for a specific entity - - A pattern with wildcards for matching multiple entities - - Wildcard examples: - - 'admin_*' matches any identifier starting with 'admin_' - - '*_test' matches any identifier ending with '_test' - - '*premium*' matches any identifier containing 'premium' - - More complex patterns can combine multiple wildcards. Detailed documentation on pattern matching rules is available at https://www.unkey.com/docs/ratelimiting/overrides#wildcard-rules - type: string - minLength: 1 - maxLength: 255 - limit: - description: |- - The maximum number of requests allowed for entities matching this override. This replaces the default limit for the namespace when applied. - - Common use cases: - - Higher limits for premium customers - - Reduced limits for abusive or suspicious entities - - Zero limit to completely block specific patterns - - Custom tier-based limits for different customer segments - format: int64 - type: integer - minimum: 0 -required: - - overrideId - - duration - - identifier - - limit diff --git a/go/apps/api/openapi/spec/common/ratelimitRequest.yaml b/go/apps/api/openapi/spec/common/ratelimitRequest.yaml deleted file mode 100644 index aa9ebb85d7..0000000000 --- a/go/apps/api/openapi/spec/common/ratelimitRequest.yaml +++ /dev/null @@ -1,55 +0,0 @@ -type: object -required: - - name - - limit - - duration - - autoApply -properties: - name: - description: |- - The name of this rate limit. This name is used to identify which limit to check during key verification. - - Best practices for limit names: - - Use descriptive, semantic names like 'api_requests', 'heavy_operations', or 'downloads' - - Be consistent with naming conventions across your application - - Create separate limits for different resource types or operation costs - - Consider using namespaced names for better organization (e.g., 'files.downloads', 'compute.training') - - You will reference this exact name when verifying keys to check against this specific limit. - type: string - example: api - minLength: 3 - maxLength: 128 - limit: - description: |- - The maximum number of operations allowed within the specified time window. - - When this limit is reached, verification requests will fail with `code=RATE_LIMITED` until the window resets. The limit should reflect: - - Your infrastructure capacity and scaling limitations - - Fair usage expectations for your service - - Different tier levels for various user types - - The relative cost of the operations being limited - - Higher values allow more frequent access but may impact service performance. - type: integer - format: int64 - minimum: 1 - duration: - description: |- - The duration for each ratelimit window in milliseconds. - - This controls how long the rate limit counter accumulates before resetting. Common values include: - - 1000 (1 second): For strict per-second limits on high-frequency operations - - 60000 (1 minute): For moderate API usage control - - 3600000 (1 hour): For less frequent but costly operations - - 86400000 (24 hours): For daily quotas - - Shorter windows provide more frequent resets but may allow large burst usage. Longer windows provide more consistent usage patterns but take longer to reset after limit exhaustion. - type: integer - format: int64 - minimum: 1000 - autoApply: - description: |- - Whether this ratelimit should be automatically applied when verifying a key. - type: boolean - default: false diff --git a/go/apps/api/openapi/spec/common/ratelimitResponse.yaml b/go/apps/api/openapi/spec/common/ratelimitResponse.yaml deleted file mode 100644 index 7bcdd37653..0000000000 --- a/go/apps/api/openapi/spec/common/ratelimitResponse.yaml +++ /dev/null @@ -1,40 +0,0 @@ -type: object -properties: - id: - type: string - minLength: 8 - maxLength: 255 - pattern: "^rl_[a-zA-Z0-9_]+$" - description: Unique identifier for this rate limit configuration. - example: rl_1234567890abcdef - name: - type: string - minLength: 1 - maxLength: 128 - description: Human-readable name for this rate limit. - example: api_requests - limit: - type: integer - format: int64 - minimum: 1 - maximum: 1000000 - description: Maximum requests allowed within the time window. - example: 1000 - duration: - type: integer - format: int64 - minimum: 1000 - maximum: 2592000000 - description: Rate limit window duration in milliseconds. - example: 3600000 - autoApply: - type: boolean - description: Whether this rate limit was automatically applied when verifying the key. - example: true -required: - - id - - name - - limit - - duration - - autoApply -additionalProperties: false diff --git a/go/apps/api/openapi/spec/common/role.yaml b/go/apps/api/openapi/spec/common/role.yaml deleted file mode 100644 index b096c075ae..0000000000 --- a/go/apps/api/openapi/spec/common/role.yaml +++ /dev/null @@ -1,41 +0,0 @@ -type: object -properties: - id: - type: string - description: | - The unique identifier for this role within Unkey's system. - Generated automatically when the role is created and used to reference this role in API operations. - Always begins with 'role_' followed by alphanumeric characters and underscores. - example: role_1234567890abcdef - name: - type: string - description: | - The human-readable name for this role that describes its function. - Should be descriptive enough for administrators to understand what access this role provides. - Use clear, semantic names that reflect the job function or responsibility level. - Names must be unique within your workspace to avoid confusion during role assignment. - example: "support.readonly" - description: - type: string - description: | - Optional detailed explanation of what this role encompasses and what access it provides. - Helps team members understand the role's scope, intended use cases, and security implications. - Include information about what types of users should receive this role and what they can accomplish. - Not visible to end users - this is for internal documentation and access control audits. - example: "Provides read-only access for customer support representatives to view user accounts and support tickets" - permissions: - type: array - items: - "$ref": "./Permission.yaml" - maxItems: 100 - description: | - Complete list of permissions currently assigned to this role. - Each permission grants specific access rights that will be inherited by any keys or users assigned this role. - Use this list to understand the full scope of access provided by this role. - Permissions can be added or removed from roles without affecting the role's identity or other properties. - Empty array indicates a role with no permissions currently assigned. -required: - - id - - name - - permissions -additionalProperties: false diff --git a/go/apps/api/openapi/spec/error/badRequestErrorDetails.yaml b/go/apps/api/openapi/spec/error/badRequestErrorDetails.yaml deleted file mode 100644 index 65430a4da5..0000000000 --- a/go/apps/api/openapi/spec/error/badRequestErrorDetails.yaml +++ /dev/null @@ -1,19 +0,0 @@ -allOf: - - $ref: "./BaseError.yaml" - - type: object - properties: - errors: - description: List of individual validation errors that occurred in the - request. Each error provides specific details about what failed validation, - where the error occurred in the request, and suggestions for fixing - it. This granular information helps developers quickly identify and - resolve multiple issues in a single request without having to make repeated - API calls. - items: - $ref: "./ValidationError.yaml" - type: array - required: - - errors -description: Extended error details specifically for bad request (400) errors. - This builds on the BaseError structure by adding an array of individual validation - errors, making it easy to identify and fix multiple issues at once. diff --git a/go/apps/api/openapi/spec/error/badRequestErrorResponse.yaml b/go/apps/api/openapi/spec/error/badRequestErrorResponse.yaml deleted file mode 100644 index 6242e91783..0000000000 --- a/go/apps/api/openapi/spec/error/badRequestErrorResponse.yaml +++ /dev/null @@ -1,16 +0,0 @@ -type: object -required: - - meta - - error -properties: - meta: - $ref: "../common/Meta.yaml" - error: - $ref: "./BadRequestErrorDetails.yaml" -description: Error response for invalid requests that cannot be processed due - to client-side errors. This typically occurs when request parameters are missing, - malformed, or fail validation rules. The response includes detailed information - about the specific errors in the request, including the location of each error - and suggestions for fixing it. When receiving this error, check the 'errors' - array in the response for specific validation issues that need to be addressed - before retrying. diff --git a/go/apps/api/openapi/spec/error/baseError.yaml b/go/apps/api/openapi/spec/error/baseError.yaml deleted file mode 100644 index ab464f3268..0000000000 --- a/go/apps/api/openapi/spec/error/baseError.yaml +++ /dev/null @@ -1,40 +0,0 @@ -properties: - detail: - description: A human-readable explanation specific to this occurrence of - the problem. This provides detailed information about what went wrong - and potential remediation steps. The message is intended to be helpful - for developers troubleshooting the issue. - example: Property foo is required but is missing. - type: string - status: - description: HTTP status code that corresponds to this error. This will - match the status code in the HTTP response. Common codes include `400` (Bad - Request), `401` (Unauthorized), `403` (Forbidden), `404` (Not Found), `409` (Conflict), - and `500` (Internal Server Error). - example: 404 - format: int - type: integer - title: - description: - A short, human-readable summary of the problem type. This remains - constant from occurrence to occurrence of the same problem and should be - used for programmatic handling. - example: Not Found - type: string - type: - description: A URI reference that identifies the problem type. This provides - a stable identifier for the error that can be used for documentation lookups - and programmatic error handling. When followed, this URI should provide human-readable - documentation for the problem type. - example: https://unkey.com/docs/errors/unkey/resource/not_found - type: string -required: - - title - - detail - - status - - type -type: object -additionalProperties: false -description: Base error structure following Problem Details for HTTP APIs (RFC - 7807). This provides a standardized way to carry machine-readable details of - errors in HTTP response content. diff --git a/go/apps/api/openapi/spec/error/conflictErrorResponse.yaml b/go/apps/api/openapi/spec/error/conflictErrorResponse.yaml deleted file mode 100644 index df70620217..0000000000 --- a/go/apps/api/openapi/spec/error/conflictErrorResponse.yaml +++ /dev/null @@ -1,16 +0,0 @@ -type: object -required: - - meta - - error -properties: - meta: - $ref: "../common/Meta.yaml" - error: - $ref: "./BaseError.yaml" -description: |- - Error response when the request conflicts with the current state of the resource. This occurs when: - - Attempting to create a resource that already exists - - Modifying a resource that has been changed by another operation - - Violating unique constraints or business rules - - To resolve this error, check the current state of the resource and adjust your request accordingly. diff --git a/go/apps/api/openapi/spec/error/forbiddenErrorResponse.yaml b/go/apps/api/openapi/spec/error/forbiddenErrorResponse.yaml deleted file mode 100644 index 9154d4fd18..0000000000 --- a/go/apps/api/openapi/spec/error/forbiddenErrorResponse.yaml +++ /dev/null @@ -1,16 +0,0 @@ -type: object -required: - - meta - - error -properties: - meta: - $ref: "../common/Meta.yaml" - error: - $ref: "./BaseError.yaml" -description: |- - Error response when the provided credentials are valid but lack sufficient permissions for the requested operation. This occurs when: - - The root key doesn't have the required permissions for this endpoint - - The operation requires elevated privileges that the current key lacks - - Access to the requested resource is restricted based on workspace settings - - To resolve this error, ensure your root key has the necessary permissions or contact your workspace administrator. diff --git a/go/apps/api/openapi/spec/error/internalServerErrorResponse.yaml b/go/apps/api/openapi/spec/error/internalServerErrorResponse.yaml deleted file mode 100644 index fdb52766e9..0000000000 --- a/go/apps/api/openapi/spec/error/internalServerErrorResponse.yaml +++ /dev/null @@ -1,16 +0,0 @@ -type: object -required: - - meta - - error -properties: - meta: - $ref: "../common/Meta.yaml" - error: - $ref: "./BaseError.yaml" -description: |- - Error response when an unexpected error occurs on the server. This indicates a problem with Unkey's systems rather than your request. - - When you encounter this error: - - The request ID in the response can help Unkey support investigate the issue - - The error is likely temporary and retrying may succeed - - If the error persists, contact Unkey support with the request ID diff --git a/go/apps/api/openapi/spec/error/notFoundErrorResponse.yaml b/go/apps/api/openapi/spec/error/notFoundErrorResponse.yaml deleted file mode 100644 index e73b122b04..0000000000 --- a/go/apps/api/openapi/spec/error/notFoundErrorResponse.yaml +++ /dev/null @@ -1,16 +0,0 @@ -type: object -required: - - meta - - error -properties: - meta: - $ref: "../common/Meta.yaml" - error: - $ref: "./BaseError.yaml" -description: |- - Error response when the requested resource cannot be found. This occurs when: - - The specified resource ID doesn't exist in your workspace - - The resource has been deleted or moved - - The resource exists but is not accessible with current permissions - - To resolve this error, verify the resource ID is correct and that you have access to it. diff --git a/go/apps/api/openapi/spec/error/unauthorizedErrorResponse.yaml b/go/apps/api/openapi/spec/error/unauthorizedErrorResponse.yaml deleted file mode 100644 index ee646cfed1..0000000000 --- a/go/apps/api/openapi/spec/error/unauthorizedErrorResponse.yaml +++ /dev/null @@ -1,16 +0,0 @@ -type: object -required: - - meta - - error -properties: - meta: - $ref: "../common/Meta.yaml" - error: - $ref: "./BaseError.yaml" -description: |- - Error response when authentication has failed or credentials are missing. This occurs when: - - No authentication token is provided in the request - - The provided token is invalid, expired, or malformed - - The token format doesn't match expected patterns - - To resolve this error, ensure you're including a valid root key in the Authorization header. diff --git a/go/apps/api/openapi/spec/error/validationError.yaml b/go/apps/api/openapi/spec/error/validationError.yaml deleted file mode 100644 index fd80ca20cf..0000000000 --- a/go/apps/api/openapi/spec/error/validationError.yaml +++ /dev/null @@ -1,34 +0,0 @@ -additionalProperties: false -properties: - location: - description: |- - JSON path indicating exactly where in the request the error occurred. This helps pinpoint the problematic field or parameter. Examples include: - - 'body.name' (field in request body) - - 'body.items[3].tags' (nested array element) - - 'path.apiId' (path parameter) - - 'query.limit' (query parameter) - Use this location to identify exactly which part of your request needs correction. - type: string - example: body.permissions[0].name - message: - description: Detailed error message explaining what validation rule was - violated. This provides specific information about why the field or parameter - was rejected, such as format errors, invalid values, or constraint violations. - type: string - example: Must be at least 3 characters long - fix: - description: A human-readable suggestion describing how to fix the error. - This provides practical guidance on what changes would satisfy the validation - requirements. Not all validation errors include fix suggestions, but when - present, they offer specific remediation advice. - type: string - example: Ensure the name uses only alphanumeric characters, underscores, - and hyphens -required: - - location - - message -type: object -description: - Individual validation error details. Each validation error provides - precise information about what failed, where it failed, and how to fix it, - enabling efficient error resolution. \ No newline at end of file