{ "components": { "schemas": { "CertificatesQuota": { "description": "Certificates quotas holds the limits and usage for certificates resources", "properties": { "limit": { "description": "The maximum number of TLS certificates in this project.", "format": "int32", "maximum": 1000000, "minimum": -1, "title": "Max certificates", "type": "integer" }, "usage": { "description": "The number of certificates that are currently existing in this project.", "format": "int32", "maximum": 1000000, "minimum": -1, "title": "Used certificates", "type": "integer" } }, "type": "object" }, "CreateCertificatePayload": { "description": "Uploads a PEM encoded X509 public/private key pair", "properties": { "labels": { "additionalProperties": { "type": "string" }, "description": "Labels represent user-defined metadata as key-value pairs.\nLabel count should not exceed 64 per Certificate.\n**Key Formatting Rules:**\nLength: 1-63 characters.\nCharacters: Must begin and end with [a-zA-Z0-9]. May contain dashes (-), underscores (_), dots (.), and alphanumerics in between.\nKeys starting with 'stackit-' are system-reserved; users MUST NOT manage them.\n\n**Value Formatting Rules:**\nLength: 0-63 characters (empty string explicitly allowed).\nCharacters (for non-empty values): Must begin and end with [a-zA-Z0-9]. May contain dashes (-), underscores (_), dots (.), and alphanumerics in between.\n", "example": { "cost.center": "billing.dept", "environment": "prod", "name": "my-app", "region": "" }, "type": "object" }, "name": { "description": "TLS certificate name", "example": "my-tls-certificate", "pattern": "^[0-9a-z](?:(?:[0-9a-z]|-){0,61}[0-9a-z])?$", "type": "string" }, "privateKey": { "description": "The PEM encoded private key part", "example": "-----BEGIN EC PRIVATE KEY----- MYPriV4TE+Tls/CER71fICATE...-----END EC PRIVATE KEY-----", "type": "string" }, "projectId": { "description": "Project identifier", "example": "2438ac3c-37eb-4902-adef-ed16b4431030", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "readOnly": true, "type": "string" }, "publicKey": { "description": "The PEM encoded public key part", "example": "-----BEGIN CERTIFICATE----- MYPUbLiC+Tls/CER71fICATE...-----END CERTIFICATE-----", "type": "string" }, "region": { "description": "Region", "example": "eu01", "format": "string", "pattern": "^[a-z]{2,4}[0-9]{2}$", "readOnly": true, "type": "string" } }, "type": "object" }, "Data": { "properties": { "dnsNames": { "description": "Comma-separated list of all domains and IP addresses the certificate is valid for (Subject Alternative Names).", "example": "example.com,*.example.com,192.168.1.1", "type": "string" }, "extendedKeyUsage": { "description": "Comma-separated list of purposes the cert is valid for. 'Server Auth' is required for Load Balancer use.", "example": "Server Auth,Client Auth", "type": "string" }, "fingerprintSha1": { "description": "The legacy SHA1 thumbprint. Provided for cross-referencing with older systems and browsers.", "example": "7a1b42c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4", "pattern": "^[a-fA-F0-9]{40}$", "type": "string" }, "fingerprintSha256": { "description": "The unique SHA256 hash of the raw certificate bytes. Use this as the primary unique identifier.", "example": "3e0a9ef962b07c2e24d321c075ebb88c261bae231f9ba34d6ffb003619f9645c", "pattern": "^[a-fA-F0-9]{64}$", "type": "string" }, "isCa": { "description": "Indicates if the certificate is a Certificate Authority, meaning it can sign other certificates.", "example": false, "type": "boolean" }, "isSelfSigned": { "description": "Indicates if the certificate was signed by its own private key rather than a trusted third-party CA.", "example": false, "type": "boolean" }, "issuerCn": { "description": "The Common Name of the Certificate Authority (CA) that signed and issued the certificate.", "example": "Let's Encrypt Authority X3", "type": "string" }, "keyStrength": { "description": "Human-readable summary of the public key's algorithm and bit-length or curve name.", "example": "RSA-2048", "type": "string" }, "notAfter": { "description": "The expiration timestamp. After this date, browsers will show security warnings (RFC3339 format).", "example": "2026-12-31T23:59:59Z", "type": "string" }, "notBefore": { "description": "The timestamp indicating when the certificate starts being valid (RFC3339 format).", "example": "2026-01-01T00:00:00Z", "type": "string" }, "organization": { "description": "Organization name associated with the certificate subject.", "example": "Acme Corp International", "type": "string" }, "publicKeyAlgorithm": { "description": "The cryptographic algorithm used to generate the public/private key pair.", "example": "RSA", "type": "string" }, "serialNumber": { "description": "The unique serial number assigned by the CA, represented in uppercase hexadecimal format.", "example": "5FDE32AB10C44598", "type": "string" }, "signatureAlgorithm": { "description": "The algorithm used by the CA to sign this certificate.", "example": "SHA256-RSA", "type": "string" }, "subjectCn": { "description": "The primary identity of the certificate. Fallback sequence: Common Name -\u003e First DNS Name -\u003e Full Subject String.", "example": "www.example.com", "type": "string" } }, "type": "object" }, "DeleteCertificateResponse": { "description": "DeleteCertificateResponse returns has empty body if successful.", "type": "object" }, "GetCertificateResponse": { "description": "GetCertificateResponse returns name, id and public key", "properties": { "data": { "$ref": "#/components/schemas/Data" }, "id": { "description": "The certificates resource id", "example": "my-tls-certificate-v1-123456", "pattern": "^[0-9a-z](?:(?:[0-9a-z]|-){0,251}[0-9a-z])?$", "type": "string" }, "labels": { "additionalProperties": { "type": "string" }, "description": "Labels represent user-defined metadata as key-value pairs.\nLabel count should not exceed 64 per Certificate.\n**Key Formatting Rules:**\nLength: 1-63 characters.\nCharacters: Must begin and end with [a-zA-Z0-9]. May contain dashes (-), underscores (_), dots (.), and alphanumerics in between.\nKeys starting with 'stackit-' are system-reserved; users MUST NOT manage them.\n\n**Value Formatting Rules:**\nLength: 0-63 characters (empty string explicitly allowed).\nCharacters (for non-empty values): Must begin and end with [a-zA-Z0-9]. May contain dashes (-), underscores (_), dots (.), and alphanumerics in between.\n", "example": { "cost.center": "billing.dept", "environment": "prod", "name": "my-app", "region": "" }, "type": "object" }, "name": { "description": "Certificate display name", "example": "my-tls-certificate", "pattern": "^[0-9a-z](?:(?:[0-9a-z]|-){0,251}[0-9a-z])?$", "type": "string" }, "publicKey": { "description": "The PEM encoded public key part", "example": "-----BEGIN CERTIFICATE----- MYPUbLiC+Tls/CER71fICATE...-----END CERTIFICATE-----", "type": "string" }, "region": { "description": "Region of the LoadBalancer", "example": "eu01", "type": "string" }, "usage": { "$ref": "#/components/schemas/Usage" } }, "type": "object" }, "GetQuotaResponse": { "properties": { "projectId": { "description": "Project identifier", "example": "2438ac3c-37eb-4902-adef-ed16b4431030", "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$", "readOnly": true, "type": "string" }, "quotas": { "$ref": "#/components/schemas/Quotas" }, "region": { "description": "Region", "example": "eu01", "format": "string", "pattern": "^[a-z]{2,4}[0-9]{2}$", "readOnly": true, "type": "string" } }, "type": "object" }, "GoogleProtobufAny": { "additionalProperties": true, "description": "Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.", "properties": { "@type": { "description": "The type of the serialized message.", "type": "string" } }, "type": "object" }, "ListCertificatesResponse": { "description": "ListCertificateResponse returns a list of certificate responses", "properties": { "items": { "items": { "$ref": "#/components/schemas/GetCertificateResponse" }, "type": "array" }, "nextPageId": { "description": "Continue token from the ListCertificatesResponse with Limit option", "example": "eyJ2IjoibWV0YS5rOHMuaW8vdjEiLCJydiI6NTQ1Njk3ODA2LCJzdGFydCI6Im15LWFsYi1uZXdcdTAwMDAifQ", "format": "string", "pattern": "^[0-9a-z](?:(?:[0-9a-z]|-){0,61}[0-9a-z])?$", "type": "string" } }, "type": "object" }, "Quotas": { "description": "Quotas holds the specific quota elements for different resources", "properties": { "certificates": { "$ref": "#/components/schemas/CertificatesQuota" } }, "type": "object" }, "Status": { "description": "The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).", "properties": { "code": { "description": "The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].", "format": "int32", "type": "integer" }, "details": { "description": "A list of messages that carry the error details. There is a common set of message types for APIs to use.", "items": { "$ref": "#/components/schemas/GoogleProtobufAny" }, "type": "array" }, "message": { "description": "A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.", "type": "string" } }, "type": "object" }, "Usage": { "properties": { "count": { "description": "Number of listeners using this certificate.", "format": "int32", "type": "integer" }, "items": { "description": "List of Load Balancers with their associated listeners that use this certificate.", "items": { "$ref": "#/components/schemas/UsageItem" }, "type": "array" } }, "type": "object" }, "UsageItem": { "properties": { "listenerNames": { "description": "The list of listener names in this Load Balancer, that are using the certificate.", "example": [ "https-443", "api-8443", "legacy-tls" ], "items": { "type": "string" }, "type": "array" }, "loadBalancerName": { "description": "The display name of the Load Balancer.", "example": "edge-lb-production", "type": "string" } }, "type": "object" } } }, "info": { "description": "This API offers the ability to store TLS certificates, which can be used by load balancing servers in STACKIT. They can be between consumer and load balancing server and/or between load balancing server and endpoint server.", "title": "STACKIT Application Load Balancer Certificates API", "version": "2.0.0" }, "openapi": "3.0.3", "paths": { "/v2/projects/{projectId}/regions/{region}/certificates": { "get": { "description": "ListCertificates will return the list of TLS certificates in a project.", "operationId": "ListCertificates", "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "region", "required": true, "schema": { "type": "string" } }, { "description": "page_size specifies how many certificates should be returned on this page. Must be a positive number \u003c= 1000", "in": "query", "name": "pageSize", "schema": { "type": "string" } }, { "description": "page_id is a page identifier returned by the previous response and is used to request the next page", "in": "query", "name": "pageId", "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCertificatesResponse" } } }, "description": "OK" }, "400": { "description": "One or more fields are invalid." }, "401": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Status" } } }, "description": "Unauthorized" }, "403": { "description": "this project_id is not allowed to try this API" }, "410": { "description": "page_id is expired" }, "500": { "description": "internal error - please retry again later or contact support if the issue persists" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }, "description": "Default error response" } }, "summary": "Retrieve the list of TLS certificate stored in a project.", "x-stackit-authorization": { "actions": [ "alb.certificateservice.certificate.list" ], "resource-id": "projectId", "resource-id-type": "dynamic", "resource-type": "project", "service-enablement": { "services": [ "cloud.stackit.loadbalancer" ] } } }, "post": { "description": "CreateCertificate will store a TLS certificate in a project.", "operationId": "CreateCertificate", "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "region", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCertificatePayload" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCertificateResponse" } } }, "description": "OK" }, "400": { "description": "One or more fields are invalid." }, "401": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Status" } } }, "description": "Unauthorized" }, "403": { "description": "this project_id is not allowed to try this API" }, "429": { "description": "maximum number of certificates is reached - please contact support to increase it" }, "500": { "description": "internal error - please retry again later or contact support if the issue persists" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }, "description": "Default error response" } }, "summary": "Store a TLS certificate in a project.", "x-stackit-authorization": { "actions": [ "alb.certificateservice.certificate.create" ], "resource-id": "projectId", "resource-id-type": "dynamic", "resource-type": "project", "service-enablement": { "services": [ "cloud.stackit.loadbalancer" ] } } } }, "/v2/projects/{projectId}/regions/{region}/certificates/{id}": { "delete": { "description": "DeleteCertificate will delete the stored TLS certificate.", "operationId": "DeleteCertificate", "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "region", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteCertificateResponse" } } }, "description": "OK" }, "400": { "description": "certificate is used by a load balancer" }, "401": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Status" } } }, "description": "Unauthorized" }, "403": { "description": "this project_id is not allowed to try this API" }, "500": { "description": "internal error - please retry again later or contact support if the issue persists" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }, "description": "Default error response" } }, "summary": "Delete a stored TLS certificate in a project.", "x-stackit-authorization": { "actions": [ "alb.certificateservice.certificate.delete" ], "resource-id": "projectId", "resource-id-type": "dynamic", "resource-type": "project", "service-enablement": { "services": [ "cloud.stackit.loadbalancer" ] } } }, "get": { "description": "GetCertificate will return the public parts of a stored TLS certificate.", "operationId": "GetCertificate", "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "region", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCertificateResponse" } } }, "description": "OK" }, "400": { "description": "One or more fields are invalid." }, "401": { "content": { "*/*": { "schema": { "$ref": "#/components/schemas/Status" } } }, "description": "Unauthorized" }, "403": { "description": "this project_id is not allowed to try this API" }, "404": { "description": "certificate not found" }, "500": { "description": "internal error - please retry again later or contact support if the issue persists" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }, "description": "Default error response" } }, "summary": "Retrieve the public parts of a stored TLS certificate.", "x-stackit-authorization": { "actions": [ "alb.certificateservice.certificate.get" ], "resource-id": "projectId", "resource-id-type": "dynamic", "resource-type": "project", "service-enablement": { "services": [ "cloud.stackit.loadbalancer" ] } } } }, "/v2/projects/{projectId}/regions/{region}/quotas": { "get": { "description": "Retrieves the configured TLS certificate quota for the project. Limit can be changed via service request.", "operationId": "GetQuota", "parameters": [ { "in": "path", "name": "projectId", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "region", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetQuotaResponse" } } }, "description": "OK" }, "400": { "description": "One or more fields are invalid." }, "401": { "content": { "text/plain": { "schema": { "type": "string" } } }, "description": "Unauthorized" }, "403": { "description": "this projectId is not allowed to try this API" }, "500": { "description": "internal error - please retry again later or contact support if the issue persists" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Status" } } }, "description": "Default error response" } }, "summary": "Get the quota for TLS certificates in a project.", "x-stackit-authorization": { "actions": [ "alb.certificateservice.quota.get" ], "resource-id": "projectId", "resource-id-type": "dynamic", "resource-type": "project", "service-enablement": { "services": [ "cloud.stackit.loadbalancer" ] } } } } }, "security": [ { "bearerAuth": [] } ], "servers": [ { "url": "https://certificates.api.stackit.cloud", "variables": { "region": { "default": "global" } } } ] }