{"openapi":"3.1.0","info":{"title":"Certificate Authority Manager API","version":"1.0.0","description":"REST API for managing mTLS Certificate Authority operations including CA initialization, certificate issuance, revocation, renewal, and monitoring for the SwePay payment gateway."},"servers":[{"url":"https://ca.swepay.com.br","description":"API Gateway"}],"paths":{"/v1/ca/initialize":{"post":{"operationId":"InitializeCA","summary":"Initialize Certificate Authority","description":"Creates and initializes a new root Certificate Authority for the authenticated tenant. Generates a self-signed CA certificate and stores the private key securely in AWS Secrets Manager.","tags":["Certificate Authority"],"security":[{"JwtBearer":[]}],"requestBody":{"required":"true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeCARequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitializeCACommandResponse"}}}},"400":{"description":"Bad Request","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"409":{"description":"Conflict","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/certificates":{"get":{"operationId":"ListCertificates","summary":"List all certificates","description":"Returns a list of all certificates issued for the authenticated tenant, including their status, serial number, and expiration details.","tags":["Certificates"],"security":[{"JwtBearer":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListCertificatesQueryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}},"post":{"operationId":"CreateCertificate","summary":"Issue a new client certificate","description":"Issues a new X.509 client certificate signed by the tenant\u0027s root CA. The certificate includes CRL Distribution Points and Authority Information Access extensions.","tags":["Certificates"],"security":[{"JwtBearer":[]}],"requestBody":{"required":"true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCertificateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCertificateCommandResponse"}}}},"400":{"description":"Bad Request","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"404":{"description":"Not Found","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/certificates/{certificateId}":{"get":{"operationId":"GetCertificate","summary":"Get certificate by ID","description":"Returns the full details of a specific certificate, including the PEM-encoded certificate, status, issuance and expiration dates, and revocation information if applicable.","tags":["Certificates"],"security":[{"JwtBearer":[]}],"parameters":[{"name":"certificateId","in":"path","required":"true","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCertificateQueryResponse"}}}},"404":{"description":"Not Found","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/certificates/{certificateId}/renew":{"post":{"operationId":"RenewCertificate","summary":"Renew a certificate","description":"Renews an existing certificate by issuing a new one with the same attributes but a new validity period. The original certificate remains valid until its natural expiration.","tags":["Certificates"],"security":[{"JwtBearer":[]}],"parameters":[{"name":"certificateId","in":"path","required":"true","schema":{"type":"string"}}],"requestBody":{"required":"true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenewCertificateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenewCertificateCommandResponse"}}}},"400":{"description":"Bad Request","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"404":{"description":"Not Found","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/certificates/{certificateId}/revoke":{"post":{"operationId":"RevokeCertificate","summary":"Revoke a certificate","description":"Revokes a previously issued certificate with the specified reason. The certificate will be added to the Certificate Revocation List (CRL) and will no longer be considered valid.","tags":["Certificates"],"security":[{"JwtBearer":[]}],"parameters":[{"name":"certificateId","in":"path","required":"true","schema":{"type":"string"}}],"requestBody":{"required":"true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeCertificateRequest"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RevokeCertificateCommandResponse"}}}},"400":{"description":"Bad Request","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"404":{"description":"Not Found","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v1/certificates/expiring":{"get":{"operationId":"GetExpiringCertificates","summary":"Get expiring certificates for the authenticated tenant","description":"Returns certificates for the authenticated tenant expiring within the specified number of days. Query parameter \u0027days\u0027 defaults to 30.","tags":["Certificates"],"security":[{"JwtBearer":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetExpiringCertificatesQueryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/certificates":{"post":{"operationId":"CreateCertificateV2","summary":"Issue a client certificate with custom extensions","description":"Issues a new X.509 client certificate with optional custom key-value extensions embedded as individual OID extensions (1.3.6.1.4.1.99999.2.{n}). Maximum 10 custom extensions, each key and value up to 255 characters.","tags":["Certificates"],"security":[{"JwtBearer":[]}],"requestBody":{"required":"true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCertificateV2Request"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCertificateCommandResponse"}}}},"400":{"description":"Bad Request","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"404":{"description":"Not Found","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}},"/v2/certificates/{certificateId}/renew":{"post":{"operationId":"RenewCertificateV2","summary":"Renew a certificate preserving custom extensions","description":"Renews an existing certificate preserving all custom X.509 extensions from the original certificate. The ClientId and all custom key-value extensions are copied to the new certificate.","tags":["Certificates"],"security":[{"JwtBearer":[]}],"parameters":[{"name":"certificateId","in":"path","required":"true","schema":{"type":"string"}}],"requestBody":{"required":"true","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenewCertificateV2Request"}}}},"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RenewCertificateCommandResponse"}}}},"400":{"description":"Bad Request","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"404":{"description":"Not Found","content":{"application/problem\u002Bjson":{"schema":{"type":"object"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}},"components":{"schemas":{"InitializeCAResponse":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid","description":"The tenant ID"},"caCertificateId":{"type":"string","format":"uuid","description":"The generated CA certificate ID"},"message":{"type":"string","description":"Success message"}}},"CreateCertificateResponse":{"type":"object","properties":{"certificateId":{"type":"string","format":"uuid","description":"The generated certificate ID"},"thumbprint":{"type":"string","description":"Certificate thumbprint (SHA-256)"},"serialNumber":{"type":"string","description":"Certificate serial number"},"expiresAt":{"type":"string","format":"date-time","description":"Certificate expiration date"}}},"RevokeCertificateResponse":{"type":"object","properties":{"certificateId":{"type":"string","format":"uuid"},"status":{"type":"string","example":"Revoked"},"revokedAt":{"type":"string","format":"date-time"}}},"RenewCertificateResponse":{"type":"object","properties":{"certificateId":{"type":"string","format":"uuid"},"newThumbprint":{"type":"string"},"newSerialNumber":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},"CertificateDetail":{"type":"object","properties":{"certificateId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"commonName":{"type":"string"},"thumbprint":{"type":"string"},"serialNumber":{"type":"string"},"status":{"type":"string","enum":["Active","Revoked","Expired"]},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"revokedAt":{"type":"string","format":"date-time","nullable":"true"}}},"CertificateSummary":{"type":"object","properties":{"certificateId":{"type":"string","format":"uuid"},"commonName":{"type":"string"},"status":{"type":"string"},"thumbprint":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},"ListCertificatesResponse":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"certificates":{"type":"array","items":{"$ref":"#/components/schemas/CertificateSummary"}}}},"ExpiringCertificateSummary":{"type":"object","properties":{"certificateId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"commonName":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"daysUntilExpiry":{"type":"integer"}}},"ExpiringCertificatesResponse":{"type":"object","properties":{"days":{"type":"integer"},"certificates":{"type":"array","items":{"$ref":"#/components/schemas/ExpiringCertificateSummary"}}}},"CreateCertificateCommandResponse":{"type":"object","properties":{"certificateId":{"type":"string","format":"uuid"},"serialNumber":{"type":"string"},"certificatePem":{"type":"string"},"privateKeyPem":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"certificateDownloadUrl":{"type":"string"},"privateKeyDownloadUrl":{"type":"string"},"downloadUrlExpiresAt":{"type":"string","format":"date-time"},"pfxBase64":{"type":"string"},"password":{"type":"string"},"pfxDownloadUrl":{"type":"string"}},"required":["certificateId","serialNumber","expiresAt"]},"CreateCertificateRequest":{"type":"object","properties":{"clientId":{"type":"string"},"commonName":{"type":"string"},"organization":{"type":"string"},"organizationalUnit":{"type":"string"},"country":{"type":"string"},"validityDays":{"type":"integer","format":"int32"},"responseFormat":{"type":"string","enum":["Text","File"]},"passwordProtected":{"type":"boolean"}},"required":["clientId","commonName","organization","organizationalUnit","country","validityDays"]},"CreateCertificateV2Request":{"type":"object","properties":{"clientId":{"type":"string"},"commonName":{"type":"string"},"organization":{"type":"string"},"organizationalUnit":{"type":"string"},"country":{"type":"string"},"validityDays":{"type":"integer","format":"int32"},"customExtensions":{"type":"object"},"responseFormat":{"type":"string","enum":["Text","File"]},"passwordProtected":{"type":"boolean"}},"required":["clientId","commonName","organization","organizationalUnit","country","validityDays"]},"GetCertificateQuery":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"},"certificateId":{"type":"string","format":"uuid"}},"required":["tenantId","certificateId"]},"GetCertificateQueryResponse":{"type":"object","properties":{"certificateId":{"type":"string","format":"uuid"},"tenantId":{"type":"string","format":"uuid"},"clientId":{"type":"string"},"commonName":{"type":"string"},"serialNumber":{"type":"string"},"certificatePem":{"type":"string"},"status":{"type":"string","enum":["Active","Revoked","Expired"]},"issuedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"revokedAt":{"type":"string","format":"date-time"},"revocationReason":{"type":"string"},"daysUntilExpiration":{"type":"integer","format":"int32"}},"required":["certificateId","tenantId","clientId","commonName","serialNumber","certificatePem","status","issuedAt","expiresAt","daysUntilExpiration"]},"GetExpiringCertificatesQuery":{"type":"object","properties":{"daysUntilExpiration":{"type":"integer","format":"int32"},"tenantFilter":{"type":"string","format":"uuid"}},"required":["daysUntilExpiration"]},"GetExpiringCertificatesQueryResponse":{"type":"object","properties":{"certificates":{"type":"array","items":{"$ref":"#/components/schemas/ExpiringCertificateSummary"}}},"required":["certificates"]},"InitializeCACommandResponse":{"type":"object","properties":{"caId":{"type":"string","format":"uuid"},"certificatePem":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["caId","certificatePem","expiresAt"]},"InitializeCARequest":{"type":"object","properties":{"commonName":{"type":"string"},"organization":{"type":"string"},"country":{"type":"string"},"validityYears":{"type":"integer","format":"int32"}},"required":["commonName","organization","country","validityYears"]},"ListCertificatesQuery":{"type":"object","properties":{"tenantId":{"type":"string","format":"uuid"}},"required":["tenantId"]},"ListCertificatesQueryResponse":{"type":"object","properties":{"certificates":{"type":"array","items":{"$ref":"#/components/schemas/CertificateSummary"}}},"required":["certificates"]},"RenewCertificateCommandResponse":{"type":"object","properties":{"newCertificateId":{"type":"string","format":"uuid"},"serialNumber":{"type":"string"},"certificatePem":{"type":"string"},"privateKeyPem":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"},"certificateDownloadUrl":{"type":"string"},"privateKeyDownloadUrl":{"type":"string"},"downloadUrlExpiresAt":{"type":"string","format":"date-time"},"pfxBase64":{"type":"string"},"password":{"type":"string"},"pfxDownloadUrl":{"type":"string"}},"required":["newCertificateId","serialNumber","expiresAt"]},"RenewCertificateRequest":{"type":"object","properties":{"validityDays":{"type":"integer","format":"int32"},"responseFormat":{"type":"string","enum":["Text","File"]},"passwordProtected":{"type":"boolean"}},"required":["validityDays"]},"RenewCertificateV2Request":{"type":"object","properties":{"validityDays":{"type":"integer","format":"int32"},"responseFormat":{"type":"string","enum":["Text","File"]},"passwordProtected":{"type":"boolean"}},"required":["validityDays"]},"RevokeCertificateCommandResponse":{"type":"object","properties":{"certificateId":{"type":"string","format":"uuid"},"revokedAt":{"type":"string","format":"date-time"}},"required":["certificateId","revokedAt"]},"RevokeCertificateRequest":{"type":"object","properties":{"reason":{"type":"string"},"reasonCode":{"type":"string","enum":["Unspecified","KeyCompromise","CaCompromise","AffiliationChanged","Superseded","CessationOfOperation","CertificateHold","RemoveFromCrl","PrivilegeWithdrawn","AaCompromise"]}},"required":["reason"]}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Validation failed"},"details":{"type":"array","items":{"type":"string"},"example":["CommonName is required","ValidityDays must be greater than 0"]}}}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Certificate not found"}}}}}},"Unauthorized":{"description":"Authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Unauthorized"}}}}}},"Forbidden":{"description":"Insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Forbidden"}}}}}},"InternalServerError":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"An unexpected error occurred"}}}}}}},"securitySchemes":{"JwtBearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token issued by the identity provider"}}}}