Certificate Manager (CM) REST API

openapi: 3.0.0 info: title: CM REST API version: "1.0" description: | The CM REST API is a HTTP-based service used for interacting with CM. It supports ways of performing certificate creation, searching, revocation, reinstatement, registrations and procedure listing through HTTP REST calls. ## HTTP Client Authentication The CM REST API requires TLS client authentication using a CM officer certificate, to identify the caller. The client TLS certificate must be an officer certificate, and must be issued by one of the CAs that are present in the PGWY Tomcat trust store. The officer must have all of the roles configured by the `requiredRoRoles` setting in `api.properties`. ## Signed requests Furthermore, operations that are sent to the CA that write or modify data, such as revoking, reinstating and issuing certificates requires the request data to be signed by a CM officer when sending the command to the CA. This signing can be done either by PGWY itself (VRO), or by PGWY requesting a signature from the caller. Signing by caller is the default. ### VRO signing To make PGWY sign such requests, PGWY must be configured to act as a Virtual Registration Officer (VRO) and thereby sign the requests on the caller's behalf. This is done by enabling server-side signing in the server configuration (`api.properties`). 1. Example request with VRO signing: ``` POST /certificates/pkcs10 pkcs10=(binary data) ``` 2. Server response: ``` (pkcs#7 data containing DER-encoded certificate) ``` ### Signing by caller If PGWY is not configured to act as VRO, then all operations that require a signature will return the request data to the caller for signing using the CM officer's key. The request to sign is returned as the `dataToSign` json field, base64-encoded. The caller is then expected to sign the request and re-send the request with the signature in a field named `signature`. 1. Example request with signature by caller: ``` POST /certificates/pkcs10 pkcs10=(binary data) ``` 2. Server response: ``` Http Status: 200 (OK) { "error":-19, "msg":"Sign request and send again", "dataToSign":"MIIC8...Rva2Vu" } ``` 3. Caller signs request and sends again: ``` POST /certificates/pkcs10 pkcs10=(binary data) signature=(base64 encoded signature) ``` 4. Server response: ``` (pkcs#7 data containing DER-encoded certificate) ``` ### Implementation details and example code for caller signature Alongside this document are two examples on how to perform the CMS (PKCS#7) based signature of the 'dataToSign' blob. The signature requires that the original data (the 'dataToSign' blob) is encapsulated and that it is in DER-encoded format. 1. OpenSSL: ``` See accompanied file 'APISigningWithOpenSSL.sh' ``` 2. BouncyCastle: ``` See accompanied file 'APISigningWithBouncyCastle.java' ``` servers: - url: https://{hostname}:{port}/{basePath} description: PGWY variables: hostname: default: localhost port: enum: - '8444' - '8443' - '443' default: '8444' basePath: default: pgwy/api paths: /certificates: get: operationId: listCertificates summary: List certificates description: | Returns a list of certificates that match the provided search parameters. tags: - Certificates parameters: - $ref: '#/components/parameters/searchLimit' - $ref: '#/components/parameters/searchOffset' - name: cardSerialNumber in: query description: Serial number of the card the certificate is on. schema: type: string - $ref: '#/components/parameters/certificateSerialNumber' - $ref: '#/components/parameters/revocationTimeFrom' - $ref: '#/components/parameters/revocationTimeTo' - $ref: '#/components/parameters/revocationReason' - $ref: '#/components/parameters/isNotRevoked' - name: subjectCommonName in: query description: The common name ( CN ) of the subject of the certificate. schema: type: string - name: subjectGivenName in: query description: The given name ( GN ) of the subject of the certificate. schema: type: string - name: subjectSurName in: query description: The surname ( SN ) of the subject of the certificate. schema: type: string - name: subjectOrganisationName in: query description: The name of the organisation ( O ) of the subject of the certificate. schema: type: string - name: subjectOrganisationUnit in: query description: The name of the organisational unit ( OU ) of the subject of the certificate. schema: type: string - name: subjectSerialNumber in: query description: The serial number of the subject of the certificate. schema: type: string - name: subjectCountry in: query description: The country ( C ) of the subject of the certificate. schema: type: string - $ref: '#/components/parameters/publicationAllowed' - $ref: '#/components/parameters/publicationTimeFrom' - $ref: '#/components/parameters/publicationTimeTo' - $ref: '#/components/parameters/ocspActivationTimeFrom' - $ref: '#/components/parameters/ocspActivationTimeTo' - $ref: '#/components/parameters/validFromTimeFrom' - $ref: '#/components/parameters/validFromTimeTo' - $ref: '#/components/parameters/isNotYetValid' - $ref: '#/components/parameters/validToTimeFrom' - $ref: '#/components/parameters/validToTimeTo' - $ref: '#/components/parameters/isExpired' - $ref: '#/components/parameters/field1' - $ref: '#/components/parameters/field2' - $ref: '#/components/parameters/field3' - $ref: '#/components/parameters/field4' - $ref: '#/components/parameters/field5' - $ref: '#/components/parameters/field6' - $ref: '#/components/parameters/authorityKeyIdentifier' - $ref: '#/components/parameters/subjectKeyIdentifier' - $ref: '#/components/parameters/subjectType' - name: issuer in: query description: | Only return certificates whose issuer matches the provided DN. The value must be a URL encoded RFC1779 string. Example: issuer=cn%3DExample%20CM%20issuing%20CA%2Co%3DExample%20CM%2Cc%3DSE schema: type: string format: RFC1779 distinguished name string. responses: 200: description: OK - Returns an array of certificates. content: application/json: schema: type: object properties: error: $ref: "#/components/schemas/ApiResponse_Error" msg: $ref: "#/components/schemas/ApiResponse_Msg" searchHits: description: | The total number of search hits that the given search parameters would yield without pagination. type: integer certificates: description: Array of certificates type: array items: $ref: "#/components/schemas/JsonCertificate" example: error: 0 msg: "Fetched certificates" searchHits: 476 certificates: [ { subject: "Super Officer 1, System, SE", validfrom: 1475849262000, certid: "10003", certificateserialnumber: "31e96265e40b809cffa3862b073ae98b", subjectType: EE, validto: 1633615659000, status: "active" } ] 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" example: error: -14 msg: Too many hits /certificates/issuers: get: deprecated: true operationId: listIssuers summary: List available issuers description: | Returns a list of distinguished names of issuer CAs that match the provided search parameters. tags: - Certificates parameters: - $ref: '#/components/parameters/searchLimit' - $ref: '#/components/parameters/searchOffset' - $ref: '#/components/parameters/certificateSerialNumber' - $ref: '#/components/parameters/revocationTimeFrom' - $ref: '#/components/parameters/revocationTimeTo' - $ref: '#/components/parameters/revocationReason' - $ref: '#/components/parameters/publicationAllowed' - $ref: '#/components/parameters/publicationTimeFrom' - $ref: '#/components/parameters/publicationTimeTo' - $ref: '#/components/parameters/ocspActivationTimeFrom' - $ref: '#/components/parameters/ocspActivationTimeTo' - $ref: '#/components/parameters/validFromTimeFrom' - $ref: '#/components/parameters/validFromTimeTo' - $ref: '#/components/parameters/isNotYetValid' - $ref: '#/components/parameters/validToTimeFrom' - $ref: '#/components/parameters/validToTimeTo' - $ref: '#/components/parameters/isExpired' responses: 200: description: OK - Returns an array of issuer subjects. content: application/json: schema: type: object properties: error: $ref: "#/components/schemas/ApiResponse_Error" msg: $ref: "#/components/schemas/ApiResponse_Msg" searchHits: description: | The total number of search hits that the given search parameters would yield without pagination. type: integer subjects: description: Array of certificate issuer DNs. type: array items: $ref: "#/components/schemas/JsonIssuer" example: error: 0 msg: "Fetched issuers" searchHits: 476 issuers: [ { subjectDn: "cn=Example CM CA,o=Example CM,c=SE", subject: { cn: "Example CM CA", o: "Example CM", c: "SE" } } ] 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" example: error: -14 msg: Too many hits /certificates/{certid}/details: get: operationId: getCertificateDetails summary: Certificate details description: | Returns information about the certificate with the provided id. tags: - Certificates parameters: - name: certid in: path description: Certificate id required: true schema: type: string responses: 200: description: OK - Returns details about the requested certificate. content: application/json: schema: type: object properties: error: $ref: "#/components/schemas/ApiResponse_Error" msg: $ref: "#/components/schemas/ApiResponse_Msg" certificate: $ref: "#/components/schemas/JsonCertificate" example: error: 0 msg: "Fetched certificate" certificate: subject: "Super Officer 2, System, SE" validfrom: 1475849262000 certid: "10003" certificateserialnumber: "31e96265e40b809cffa3862b073ae98b" subjectType: EE validto: 1633615659000 status: "active" 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" example: error: -14 msg: "No certificate found" /certificates/{certid}/download: get: operationId: downloadCertificate summary: Download certificate description: | Returns a certificate in binary form. For X.509 certificates, the returned certificate encoding may be DER, PEM or MIME (pkcs#7), depending on the media type in the provided Accept header. tags: - Certificates parameters: - name: certid in: path description: Certificate ID. required: true schema: type: string responses: 200: description: OK - Returns the requested certificate. content: application/pkix-cert: schema: type: string format: binary application/pkcs7-mime: schema: type: string format: binary application/pem-certificate-chain: schema: description: Returns full chain including <br> certificate specified by certid. type: string format: binary application/pem-certificate-chain;depth=<value>: schema: description: ;depth=0<br>Returns full chain including <br> certificate specified by certid. <br><br> ;depth=1<br>Returns certificate specified by certid. <br><br> ;depth=value bigger than 1<br>Returns part of the chain <br> up to the given depth value, if the depth value is <br> bigger than the number of certificates in the chain <br> it returns the full chain. type: string format: binary 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" example: error: -14 msg: "No certificate found" /certificates/revoke: post: operationId: revokeCertificate summary: Revoke certificate description: Revokes the certificate(s) with the matching certificate id(s). tags: - Certificates requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: certid: description: Certificate id(s) to revoke. type: array items: type: string reason: $ref: "#/components/schemas/ApiRequest_RevocationReason" signature: $ref: "#/components/schemas/ApiRequest_Signature" required: - certid - reason responses: 200: description: OK - Requested certificates were revoked. content: application/json: schema: type: object properties: error: $ref: "#/components/schemas/ApiResponse_Error" msg: $ref: "#/components/schemas/ApiResponse_Msg" example: error: 0 msg: "1 certificate(s) has been revoked" 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponseWithCertIds" example: error: -1 msg: "Error(s) occurred during the revocation" errors: [ { certid: "1", errorcode: 907, errormessage: "The certificate was not found", servererrormessage: "Certificate with certSerNr: 1 is not found." } ] /certificates/reinstate: post: operationId: reinstateCertificate summary: Reinstate certificate description: Reinstates the certificate(s) with the matching certificate id(s). tags: - Certificates requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: certid: description: Certificate id(s) to reinstate type: array items: type: string signature: $ref: "#/components/schemas/ApiRequest_Signature" required: - certid responses: 200: description: OK - Requested certificates were reinstated. content: application/json: schema: type: object properties: error: $ref: "#/components/schemas/ApiResponse_Error" msg: $ref: "#/components/schemas/ApiResponse_Msg" example: error: 0 msg: "1 certificate(s) has been reinstated" 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponseWithCertIds" example: error: -1 msg: "Error(s) occurred during the reinstatement" errors: [ { certid: "1", errorcode: 907, errormessage: "The certificate was not found", servererrormessage: "Certificate with certSerNr: 1 is not found." } ] /certificates/pkcs10: post: operationId: issueCertificatePkcs10 summary: Create certificate from PKCS10 request description: | Creates a certificate from a PKCS10 request and returns the result as either PKCS7 or X.509 DER or PEM encoded depending on the Accept HTTP header. The PKCS#7 and PEM results will contain the chain if the token procedure had store all. Otherwise, will return only the end certificate. tags: - Certificates requestBody: required: true content: multipart/form-data: schema: type: object properties: pkcs10: description: PKCS10 request (Base64 encoded) type: string format: byte validfrom: description: | X.509 "not before" point in time. Format 'ISO 8601'. Example: 2007-03-01T13:00:00Z type: string format: date-time validto: description: | X.509 "not after" point in time. Format 'ISO 8601'. Example: 2008-05-11T15:30:00Z type: string format: date-time procname: description: | Name of token procedure that should be used to issue the certificate. If this parameter is not given, a default value set in the server side configuration will be used (`handler.(n).tokenprocedure` in `api.properties`). type: string signature: $ref: "#/components/schemas/ApiRequest_Signature" required: - pkcs10 encoding: pkcs10: contentType: application/pkcs10 responses: 200: description: OK - Returns a PKCS7 message or X509 the issued certificate. content: application/pkcs7-mime: schema: type: string format: binary application/pkix-cert: schema: type: string format: binary application/pem-certificate-chain: schema: type: string format: binary 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" /certificates/pkcs10-to-pkcs12: post: operationId: issueCertificatePkcs10ToPkcs12 summary: Issue certificate to PKCS#12 from PKCS#10 request description: | Issues a certificate from a PKCS#10 request and returns the result as PKCS#12. This endpoint is used to issue certificates for keys that are generated server-side by CM. For these cases, this endpoint is by default configured to accept unsigned PKCS#10 requests that only contain the TBS parts, and by default configured to discard the public key part specified in the PKCS#10 request. To generate the key on the server-side, the token procedure should specify an applicable key procedure. tags: - Certificates requestBody: required: true content: multipart/form-data: schema: type: object properties: pkcs10: description: PKCS10 request (Base64 encoded). type: string format: byte validfrom: description: | X.509 "not before" point in time. Format 'ISO 8601'. Example: 2007-03-01T13:00:00Z type: string format: date-time validto: description: | X.509 "not after" point in time. Format 'ISO 8601'. Example: 2008-05-11T15:30:00Z type: string format: date-time password: description: | Password to be used to protect the resulting PKCS12 archive. If this parameter is not given, the password will be generated by the server. type: string format: password procname: description: | Name of token procedure that should be used to issue the certificate. If this parameter is not given, a default value set in the server side configuration will be used (`handler.(n).tokenprocedure` in `api.properties`). type: string signature: $ref: "#/components/schemas/ApiRequest_Signature" required: - pkcs10 encoding: pkcs10: contentType: application/pkcs10 responses: 200: description: OK - Returns a PKCS12 archive with the issued certificate and key. content: application/x-pkcs12: schema: type: string format: binary 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" /certificates/{certid}/pkcs10-to-attr-cert: post: operationId: issueCertificatePkcs10ToAttrCert summary: Issue certificate to PKCS#7 or X.509 containing attribute certificate from PKCS#10 request description: | Issues an attribute certificate from a PKCS#10 request and returns the result as PKCS#7 or X.509 DER or PEM encoded depending on the Accept HTTP header. The PKCS#7 and PEM results will contain the chain if the token procedure had store all. Otherwise, will return only the end certificate. This endpoint is used to issue attribute certificates that are generated for a base certificate on server-side by CM. For these cases, this endpoint is by default configured to accept unsigned PKCS#10 requests that only contain the TBS parts. A public key is required by PKCS#10, while it is not required for issuing the attribute certificate. Therefore, by default the endpoint is configured to discard the public key part specified in the PKCS#10 request as it is not required. tags: - Certificates parameters: - $ref: '#/components/parameters/certid' requestBody: required: true content: multipart/form-data: schema: type: object properties: pkcs10: description: PKCS10 request (Base64 encoded). type: string format: byte validfrom: description: | X.509 "not before" point in time. Format 'ISO 8601'. Example: 2007-03-01T13:00:00Z type: string format: date-time validto: description: | X.509 "not after" point in time. Format 'ISO 8601'. Example: 2008-05-11T15:30:00Z type: string format: date-time procname: description: | Name of token procedure that should be used to issue the attribute certificate. If this parameter is not given, a default value set in the server side configuration will be used (`handler.(n).tokenprocedure` in `api.properties`). type: string signature: $ref: "#/components/schemas/ApiRequest_Signature" required: - pkcs10 encoding: pkcs10: contentType: application/pkcs10 responses: 200: description: OK - Returns a PKCS7 archive with the issued attribute certificate. content: application/pkcs7-mime: schema: type: string format: binary application/pkix-cert: schema: type: string format: binary application/pem-certificate-chain: schema: type: string format: binary 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" /certificates/skip: post: operationId: secureKeyInjectionPackage summary: Create a secure key injection package from a PKCS10 request description: | Creates a secure key package for IoT devices from a PKCS10 request and return the result as PKCS7. The PKCS10 request only need to include the public key and subject information and no other request data. The PKCS7 response content is an ASN.1 encoded list of the generated device keypairs, KeyPairContainers, where the public key is an encoded SubjectPublicKeyInfo (RFC 5280), and the private key is an encoded EncryptedPrivateKeyInfo (RFC 5958). KeyPairContainers ::= SEQUENCE OF KeyPairContainer KeyPairContainer ::= SEQUENCE { public SubjectPublicKeyInfo, encryptedPrivate EncryptedPrivateKeyInfo } tags: - Certificates requestBody: required: true content: multipart/form-data: schema: type: object properties: pkcs10: description: | PKCS10 request (Base64 encoded) containing the initial public key and subject information. type: string format: byte validfrom: description: | X.509 "not before" point in time. Format 'ISO 8601'. Example: 2007-03-01T13:00:00Z type: string format: date-time validto: description: | X.509 "not after" point in time. Format 'ISO 8601'. Example: 2008-05-11T15:30:00Z type: string format: date-time procname: description: | Name of token procedure that should be used to issue the certificate. If this parameter is not given, a default value set in the server side configuration will be used (`handler.(n).tokenprocedure` in `api.properties`). type: string signature: $ref: "#/components/schemas/ApiRequest_Signature" required: - pkcs10 encoding: pkcs10: contentType: application/pkcs10 responses: 200: description: OK - Returns a PKCS7 message with the issued certificate. content: application/pkcs7-mime: schema: type: string format: binary 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" /certificates/import-pki-x509: post: operationId: importPKIX509 summary: Import externally issued X.509 certificates description: | Imports X.509 certificates from an external PKI. This endpoint is used to import certificate(s) to CM issued by an external PKI. Each imported certificate may be complemented with revocation information, such as reason code and time of revocation. The request may specify a token procedure, which must be connected to a CA with a SubjectDN matching imported certificates IssuerDN. If no Token Procedure is specified, a default is used by the server. tags: - Certificates requestBody: required: true content: application/json: schema: type: object properties: procname: description: | Name of token procedure that should be used to issue the certificate. If this parameter is not given, a default value set in the server side configuration will be used. type: string importdata: description: | Array of certificate(s) to import. type: array items: type: object properties: certificate: description: | Base64 encoded certificate. type: string format: byte reason: $ref: "#/components/schemas/ApiRequest_RevocationReason" revocationtime: description: | Point in time when the certificate was revoked. type: string format: date-time required: - certificate signature: $ref: "#/components/schemas/ApiRequest_Signature" required: - importdata responses: 200: description: OK - successfully imported all certificates content: application/json: schema: type: object properties: error: $ref: "#/components/schemas/ApiResponse_Error" msg: $ref: "#/components/schemas/ApiResponse_Msg" example: error: 0 msg: "1 certificate(s) has been imported" 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponseWithJsonArrayIndex" example: error: -1 msg: "Error(s) occurred during the PKI import" errors: [ { arrayindex: 0, errorcode: -14, errormessage: "Duplicated certificate import entry", }, { arrayindex: 1, errorcode: -14, errormessage: "Unable to import certificate", servererrormessage: "Invalid certificate issuer" }, { arrayindex: 2, errorcode: -40, errormessage: "Maximum import limit exceeded", limit: 1 } ] /procedures: get: operationId: listProcedures summary: List procedures description: | Lists all token procedures that are available for the authenticated officer. tags: - Procedures responses: 200: description: OK - Returns the list of available token procedures. content: application/json: schema: type: object properties: error: $ref: "#/components/schemas/ApiResponse_Error" msg: $ref: "#/components/schemas/ApiResponse_Msg" procedures: description: Array of token procedures. type: array items: type: object properties: procid: type: string description: Unique ID of the procedure. name: type: string description: Human-readable name of the procedure. example: error: 0 msg: "Fetched procedures" procedures: [ { procid: "t-scep-registr-visible-p10", name: "SCEP Registration Visible Procedure" } ] 500: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" example: error: -1 msg: "No procedures found" /registrations/{procid}: get: operationId: listRegistrations summary: List registrations description: | The registrations endpoint returns a list of registrations done on the procedure with the matching token procedure id and, if given, the other optional parameters. tags: - Registrations parameters: - $ref: '#/components/parameters/procid' - $ref: '#/components/parameters/regid' - $ref: '#/components/parameters/fqdn' - $ref: '#/components/parameters/status' - $ref: '#/components/parameters/validity' - $ref: '#/components/parameters/officer' - $ref: '#/components/parameters/regtype' responses: 200: description: OK - Returns all registrations matching the given query parameters. content: application/json: schema: $ref: '#/components/schemas/RegistrationResponseGet' example: registrations: - regid: akZShn8u3qcOetstcL7eyfD05Tk= fqdn: 'test-1-170645' creationdate: 1565096805000 status: closed regtype: cmp validity: 7 error: 0 msg: Fetched registrations 500: $ref: '#/components/responses/ServerError' post: operationId: createRegistration summary: Creates registration description: | Either body OR file must be set. tags: - Registrations parameters: - $ref: '#/components/parameters/procid' requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateRegistration' example: fqdn: "Device Test" regtype: "cmp" status: "open" validity: "7" signature: "MIIFuwYJK..." responses: 200: $ref: '#/components/responses/RegistrationPost200' 500: $ref: '#/components/responses/RegistrationPost500' put: operationId: updateRegistration summary: Update registration description: | Updates a registration with the given data. tags: - Registrations parameters: - $ref: '#/components/parameters/procid' requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateRegistration' example: regid: "regid-1234" status: "open" validity: "always" signature: "MIIFuwYJK..." responses: 200: $ref: '#/components/responses/RegistrationUpdate200' 500: $ref: '#/components/responses/RegistrationUpdate500' /registrations/certificate/{certid}: get: operationId: getRegistrationsCertId summary: Retrieves the registration that issued the certificate. description: Retrieves the registration that issued the certificate. tags: - Registrations responses: 200: description: OK - Returns the registration. content: application/json: schema: $ref: '#/components/schemas/RegistrationCertId' 500: $ref: '#/components/responses/ServerError' parameters: - $ref: '#/components/parameters/certid' /registrations/{procid}/scep: get: operationId: listRegistrationsScep summary: List registrations under SCEP description: | The SCEP registrations endpoint returns a list of registrations done on the procedure with the matching token procedure id and, if given, the other optional parameters. tags: - Registrations/{procid}/SCEP responses: 200: description: OK - Returns all registrations matching the given query parameters. content: application/json: schema: $ref: '#/components/schemas/RegistrationResponseGet' example: registrations: - regid: CGEMNL39wUEB/srVptVCKYyD2nA= fqdn: 'test-*.example.com' creationdate: 1572490820000 officer: Super Officer 2 status: open regtype: scep validity: always encryptedpassword: MIIB...3yv6 error: 0 msg: Fetched registrations 500: $ref: '#/components/responses/ServerError' parameters: - $ref: '#/components/parameters/procid' - $ref: '#/components/parameters/regid' - $ref: '#/components/parameters/fqdn' - $ref: '#/components/parameters/status' - $ref: '#/components/parameters/validity' - $ref: '#/components/parameters/officer' post: operationId: createRegistrationScep summary: Creates registration for SCEP description: | Either body OR file must be set. tags: - Registrations/{procid}/SCEP parameters: - $ref: '#/components/parameters/procid' requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/RegistrationScep' required: - fqdn - password example: fqdn: "SCEP-1234" password: "1234" status: "open" validity: "always" signature: "MIIFuwYJK..." responses: 200: $ref: '#/components/responses/RegistrationPost200' 500: $ref: '#/components/responses/RegistrationPost500' put: operationId: updateRegistrationScep summary: Updates registration for SCEP description: | Updates a registration with the given data for SCEP protocol. tags: - Registrations/{procid}/SCEP parameters: - $ref: '#/components/parameters/procid' requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/RegistrationScep' required: - regid example: regid: "regid-1234" status: "open" validity: "7" signature: "MIIFuwYJK..." responses: 200: $ref: '#/components/responses/RegistrationUpdate200' 500: $ref: '#/components/responses/RegistrationUpdate500' /registrations/{procid}/est: get: operationId: listRegistrationsEst summary: List registrations for EST description: | The EST registrations endpoint returns a list of registrations done on the procedure with the matching token procedure id, and if given, the other optional parameters. tags: - Registrations/{procid}/EST responses: 200: description: OK - Returns all registrations matching the given query parameters. content: application/json: schema: $ref: '#/components/schemas/RegistrationResponseGet' example: registrations: - regid: 2YLD25xzE9BW84WdhRSsNFyNTvk= fqdn: 'APIClientTest_-1835737403' creationdate: 1572490406000 officer: Super Officer 1 status: open regtype: est validity: always encryptedpassword: MIIB...IX9m error: 0 msg: Fetched registrations 500: $ref: '#/components/responses/ServerError' parameters: - $ref: '#/components/parameters/procid' - $ref: '#/components/parameters/regid' - $ref: '#/components/parameters/fqdn' - $ref: '#/components/parameters/status' - $ref: '#/components/parameters/validity' - $ref: '#/components/parameters/officer' post: operationId: createRegistrationEst summary: Creates registration for EST description: | Either body OR file must be set. tags: - Registrations/{procid}/EST parameters: - $ref: '#/components/parameters/procid' requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/RegistrationEstHttpAuth' - $ref: '#/components/schemas/RegistrationEstCertAuth' required: - fqdn examples: http-authentication: value: fqdn: "*.ad.example.com" password: "1234" status: "open" validity: "7" signature: "MIIFuwYJK..." certificate-authentication: value: fqdn: "my.authentication.certificate" subject-commonname: "my.commonname.in.csr" status: "open" validity: "7" signature: "MIIFuwYJK..." responses: 200: $ref: '#/components/responses/RegistrationPost200' 500: $ref: '#/components/responses/RegistrationPost500' put: operationId: updateRegistrationEst summary: Updates registration for EST description: | Updates a registration with the given data for EST protocol. tags: - Registrations/{procid}/EST parameters: - $ref: '#/components/parameters/procid' requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/RegistrationEstHttpAuth' - $ref: '#/components/schemas/RegistrationEstCertAuth' required: - regid examples: http-authentication: value: regid: "regid-1234" fqdn: "*.ad.example.com" status: "closed" validity: "7" signature: "MIIFuwYJK..." certificate-authentication: value: regid: "regid-1234" fqdn: "my.authentication.certificate" subject-commonname: "my.new.commonname.in.csr" status: "open" validity: "3" signature: "MIIFuwYJK..." responses: 200: $ref: '#/components/responses/RegistrationUpdate200' 500: $ref: '#/components/responses/RegistrationUpdate500' /registrations/{procid}/cmp: get: operationId: listRegistrationsCmp summary: List registrations for CMP description: | The CMP registrations endpoint returns a list of registrations done on the procedure with the matching token procedure id, and if given, the other optional parameters. tags: - Registrations/{procid}/CMP responses: 200: description: OK - Returns all registrations matching the given query parameters. content: application/json: schema: $ref: '#/components/schemas/RegistrationResponseGet' example: registrations: - regid: JS2rc9cTa1jlAXxHdANTg7YEvu4= fqdn: '*.vendor.com' creationdate: 1572490601000 officer: Super Officer 2 status: open regtype: cmp validity: always encryptedpassword: MIIB...fJ8D error: 0 msg: Fetched registrations 500: $ref: '#/components/responses/ServerError' parameters: - $ref: '#/components/parameters/procid' - $ref: '#/components/parameters/regid' - $ref: '#/components/parameters/fqdn' - $ref: '#/components/parameters/status' - $ref: '#/components/parameters/validity' - $ref: '#/components/parameters/officer' post: operationId: createRegistrationCmp summary: Creates registration for CMP description: | Either body OR file must be set. tags: - Registrations/{procid}/CMP parameters: - $ref: '#/components/parameters/procid' requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/RegistrationCmp' required: - fqdn example: fqdn: "*.ad.example.com" status: "open" validity: "7" signature: "MIIFuwYJK..." responses: 200: $ref: '#/components/responses/RegistrationPost200' 500: $ref: '#/components/responses/RegistrationPost500' put: operationId: updateRegistrationCmp summary: Updates registration for CMP description: | Updates a registration with the given data for CMP protocol. tags: - Registrations/{procid}/CMP parameters: - $ref: '#/components/parameters/procid' requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/RegistrationCmp' required: - regid example: regid: "regid-1234" fqdn: "*.ad.example.com" status: "open" validity: "7" signature: "MIIFuwYJK..." responses: 200: $ref: '#/components/responses/RegistrationUpdate200' 500: $ref: '#/components/responses/RegistrationUpdate500' /registrations/{procid}/acme: get: operationId: listRegistrationsAcme summary: List registrations for ACME description: | The ACME registrations endpoint returns a list of registrations done on the procedure with the matching token procedure id, and if given, the other optional parameters. tags: - Registrations/{procid}/ACME responses: 200: description: OK - Returns all registrations matching the given query parameters. content: application/json: schema: $ref: '#/components/schemas/RegistrationResponseAcmeGet' example: registrations: - regid: 4Lvs8mYrqi73CcZjt5UFfiIa4kc= fqdn: 'keyId-63453491' creationdate: 1572490404000 officer: Super Officer 1 status: open regtype: acme validity: always error: 0 msg: Fetched registrations 500: $ref: '#/components/responses/ServerError' parameters: - $ref: '#/components/parameters/procid' - $ref: '#/components/parameters/regid' - $ref: '#/components/parameters/fqdn' - $ref: '#/components/parameters/status' - $ref: '#/components/parameters/validity' - $ref: '#/components/parameters/officer' post: operationId: createRegistrationAcme summary: Creates registration for ACME description: | Either body OR file must be set. tags: - Registrations/{procid}/ACME parameters: - $ref: '#/components/parameters/procid' requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/RegistrationAcme' required: - fqdn - hmacKey example: fqdn: "*.ad.example.com" hmacKey: "PSuC...Zoi8" status: "open" validity: "7" signature: "MIIFuwYJK..." responses: 200: $ref: '#/components/responses/RegistrationPost200' 500: $ref: '#/components/responses/RegistrationPost500' put: operationId: updateRegistrationAcme summary: Updates registration for ACME description: | Updates a registration with the given data for ACME protocol. tags: - Registrations/{procid}/ACME parameters: - $ref: '#/components/parameters/procid' requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/RegistrationAcme' required: - regid example: regid: "regid-1234" fqdn: "*.ad.example.com" status: "open" validity: "7" signature: "MIIFuwYJK..." responses: 200: $ref: '#/components/responses/RegistrationUpdate200' 500: $ref: '#/components/responses/RegistrationUpdate500' /registrations/{procid}/acme/accounts: get: operationId: listAcmeAccounts summary: Lists ACME accounts. description: | Lists all ACME accounts from a registration. Search can be limited by using the query parameter 'accountid'. tags: - Registrations/{procid}/ACME parameters: - $ref: '#/components/parameters/procid' - $ref: '#/components/parameters/accountid' responses: 200: description: OK - Account(s) successfully retrieved content: application/json: schema: $ref: '#/components/schemas/Account' example: registrations: - regid: 4Lvs8mYrqi73CcZjt5UFfiIa4kc= fqdn: 'CnY9c9OuvSEHGT3cfRkBlQ' creationdate: 1575278296000 officer: Super Officer 1 status: Active keyid: 'keyId-644251404' email: acme@example.com regType: 'acme/account' certIds: [10050, 10051, 11302] error: 0 msg: Fetched registrations 500: description: Error - Failed to retrieve accounts content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" example: error: -14 msg: "Code -14, invalid procedure id" components: schemas: ApiResponse_Error: type: integer description: | Non-zero error code if the request could not be processed, or zero if there was no error. Possible values: * 0 = Ok * -1 = General error * -7 = Missing field * -8 = Encoding error * -12 = Not initialized * -14 = Bad field value * -15 = Privilige error * -17 = Bad signature * -18 = Connection error * -19 = Signature required * -40 = Too many requests ApiResponse_Msg: type: string description: Developer message describing the outcome of the request. ApiRequest_Signature: type: string description: | Signed request (Base64 encoded). Only used when CM REST API is configured to not use VRO signing. format: byte writeOnly: true ApiRequest_RevocationReason: type: integer minimum: 0 maximum: 10 description: | Revocation reason code mapping * 0: Unspecified * 1: Key Compromise * 3: Affiliation Changed * 4: Superseded * 5: Cessation Of Operation * 6: Certificate Hold * 9: Privilege Withdrawn ApiErrorResponse: type: object properties: error: $ref: "#/components/schemas/ApiResponse_Error" msg: $ref: "#/components/schemas/ApiResponse_Msg" ApiErrorResponseWithCertIds: type: object properties: error: $ref: "#/components/schemas/ApiResponse_Error" msg: $ref: "#/components/schemas/ApiResponse_Msg" errors: type: array items: type: object properties: certid: description: Certificate ID. type: string errorcode: description: | Integer code of the problem that prevented this certificate ID from being processed. Possible values: * 901 = Already Revoked * 902 = Access Denied * 903 = Incorrect Password * 904 = Free text (non specific errorcode) * 906 = Already on hold * 907 = Certificate missing * 908 = Request not signed * 909 = Not visible from domain * 910 = Not on hold * 911 = Revocation not available extension * -1 = General error type: integer errormessage: description: | Developer message describing the problem that prevented this certificate ID from being processed. type: string servererrormessage: description: | Developer message given by the server. type: string ApiErrorResponseWithJsonArrayIndex: type: object properties: error: $ref: "#/components/schemas/ApiResponse_Error" msg: $ref: "#/components/schemas/ApiResponse_Msg" errors: type: array items: type: object properties: arrayindex: description: | Indicates the index position of the failed certificate import. type: integer errorcode: description: | Integer code of the problem that prevented this certificate ID from being processed. type: integer errormessage: description: | Developer message describing the problem that prevented this certificate from being processed. type: string servererrormessage: description: | Developer message given by the server. type: string limit: description: | Integer indicating the maximum allowed size of the JsonArray in the request. The limit is added to clarify if the error is due to the limit being exceeded. type: integer JsonIssuer: type: object description: CA details. properties: subject: type: array description: Subject items: type: object description: | Relative DN of directory attributes as per RFC1779 (for example {"cn":"somecommonname"}.) subjectDn: type: string description: Full subject DN string JsonCertificate: type: object description: Certificate details. properties: certid: type: string description: Unique ID of the certificate. status: type: string description: Human-readable status of the certificate, revoked/active. reason: type: string description: Revocation reason. revocationtime: type: string format: date-time description: Point in time when the certificate was revoked. validto: type: string format: date-time description: X.509 "not after" point in time. validfrom: type: string format: date-time description: X.509 "not before" point in time. certificateserialnumber: type: string description: Certificate serial number in hex format. subject: type: string description: Subject distinguished name. issuer: type: string description: Issuer distinguished name. keyusage: type: array items: type: string description: | List of key usage names, including those from ExtendedKeyUsage extension. subjectType: type: string description: | Identifies the subject tpye of the certificate, either an End Entity (EE) or a Certificate Authority (CA) extendedcertsearch: type: object properties: field1: type: string field2: type: string field3: type: string field4: type: string field5: type: string field6: type: string description: | List of extended certificate search criteria field values authorityKeyIdentifier: type: string description: AuthorityKeyIdentifier in hex format subjectKeyIdentifier: type: string description: SubjectKeyIdentifier in hex format required: - certid - status Regid: type: string description: The registration id. Created on the server side. readOnly: true Fqdn: type: string description: Fully qualified domain name. Validity: type: string description: | Determines for how long the registration will be open. Set in either days or 'always' to be open forever. Officer: type: string description: Officer who signed the request. Created on the server side. readOnly: true Creationdate: type: string description: Creation date of the registration. Created on the server side. readOnly: true Regtype: type: string enum: - est - cmp - scep - device - acme - acme/account description: | Determines which type the registration can be used with. Status: type: string enum: - open - closed description: | Either 'open' or 'closed'. Determines if that registration can be used for certificate creation. AccountStatus: type: string enum: - active - deactivated - revoked description: | Either 'active', 'deactivate' or 'revoked'. Determines if the account registration can be used for certificate creation. Email: type: string description: Email address used with the registration. Keyid: type: string description: Keyid of the connected pre-registration. Certids: type: array description: Array of certificate ids. items: type: string readOnly: true Accountids: type: array description: Array of ACME account ids. items: type: string # Contains base parameters common for all types of registrations RegistrationBase: properties: regid: $ref: '#/components/schemas/Regid' fqdn: $ref: '#/components/schemas/Fqdn' validity: $ref: '#/components/schemas/Validity' status: $ref: '#/components/schemas/Status' signature: $ref: "#/components/schemas/ApiRequest_Signature" Registration: type: object allOf: - $ref: '#/components/schemas/RegistrationBase' - properties: regtype: $ref: '#/components/schemas/Regtype' officer: $ref: '#/components/schemas/Officer' creationdate: $ref: '#/components/schemas/Creationdate' certids: $ref: '#/components/schemas/Certids' PreRegistrationAcme: type: object allOf: - $ref: '#/components/schemas/RegistrationBase' - properties: regtype: $ref: '#/components/schemas/Regtype' officer: $ref: '#/components/schemas/Officer' creationdate: $ref: '#/components/schemas/Creationdate' accountids: $ref: '#/components/schemas/Accountids' RegistrationScep: type: object allOf: - $ref: '#/components/schemas/RegistrationBase' - properties: ipaddress: type: string description: | IP address of the device using the registration. email: $ref: '#/components/schemas/Email' serialnumber: type: string description: | Serial number of the device using the registration. password: type: string description: | The password used to register. RegistrationEstHttpAuth: type: object allOf: - $ref: '#/components/schemas/RegistrationBase' - properties: username: type: string description: | Username used with HTTP based authentication. realm: type: string description: | Realm used with HTTP based authentication. password: type: string description: | The password used to register. RegistrationEstCertAuth: type: object allOf: - $ref: '#/components/schemas/RegistrationBase' - properties: subject-commonname: type: string description: | Commonname of the subject in the CSR to enroll for authentication-certificate-ca: type: string description: | AWB name of the CA of the device authentication certificate. RegistrationCmp: type: object allOf: - $ref: '#/components/schemas/RegistrationBase' - properties: password: type: string description: | The password used to register. RegistrationAcme: type: object allOf: - $ref: '#/components/schemas/RegistrationBase' - properties: hmacKey: type: string format: byte description: | HMAC key for ACME pre-registration (32 bytes in base64 url-safe encoding). allowedDomains: type: string description: | Comma separated string of allowed domains for ACME pre-registration. RegistrationCertId: type: object properties: registration: $ref: '#/components/schemas/Registration' error: $ref: '#/components/schemas/ApiResponse_Error' msg: $ref: '#/components/schemas/ApiResponse_Msg' Account: type: object allOf: - properties: regid: $ref: '#/components/schemas/Regid' fqdn: $ref: '#/components/schemas/Fqdn' creationdate: $ref: '#/components/schemas/Creationdate' officer: $ref: '#/components/schemas/Officer' status: $ref: '#/components/schemas/AccountStatus' keyid: $ref: '#/components/schemas/Keyid' email: $ref: '#/components/schemas/Email' certids: $ref: '#/components/schemas/Certids' CreateRegistration: allOf: - $ref: '#/components/schemas/RegistrationBase' - properties: regtype: $ref: '#/components/schemas/Regtype' required: - fqdn - regtype UpdateRegistration: allOf: - $ref: '#/components/schemas/Registration' - properties: regid: readOnly: false regtype: readOnly: true required: - regid RegistrationResponseGet: type: object properties: registrations: type: array description: Array of registrations connected to the given procid. items: $ref: '#/components/schemas/Registration' error: $ref: '#/components/schemas/ApiResponse_Error' msg: $ref: '#/components/schemas/ApiResponse_Msg' RegistrationResponseAcmeGet: type: object properties: registrations: type: array description: Array of registrations connected to the given procid. items: $ref: '#/components/schemas/PreRegistrationAcme' error: $ref: '#/components/schemas/ApiResponse_Error' msg: $ref: '#/components/schemas/ApiResponse_Msg' RegistrationResponsePostOrPut: type: object properties: registration: type: object properties: regid: $ref: '#/components/schemas/Regid' error: $ref: "#/components/schemas/ApiResponse_Error" msg: $ref: "#/components/schemas/ApiResponse_Msg" # Defines common parameters used by multiple GET operations parameters: procid: name: procid in: path description: Token procedure id required: true schema: type: string regid: name: regid in: query description: Registration id schema: type: string certid: name: certid in: path description: Certificate id required: true schema: type: string accountid: name: accountid in: query description: Account id, allows wildcard(*) schema: type: string fqdn: name: fqdn in: query description: Fully qualified domain name. schema: type: string status: name: status in: query description: Registration status schema: enum: - open - closed type: string validity: name: validity in: query description: Number of days the registration will be open or 'always'. schema: type: string regtype: name: regtype in: query description: Registration type of the registration. schema: $ref: '#/components/schemas/Regtype' email: name: email in: query description: Email address schema: type: string ipaddress: name: ipaddress in: query description: IP address schema: type: string serialnumber: name: serialnumber in: query description: Certificate serialnumber as hex. schema: type: string password: name: password in: query description: The password used to register. schema: type: string username: name: username in: query description: The username used to register. schema: type: string realm: name: realm in: query description: The realm the user should be connected with. schema: type: string subject-commonname: name: subject-commonname in: query description: The commonname of the subject to be enrolled schema: type: string hmacKey: name: hmacKey in: query description: | HMAC key for ACME pre-registration (32 bytes in base64 url-safe encoding). The HMAC Key Id must also be specified in the fqdn field. schema: type: string allowedDomains: name: allowedDomains in: query description: Comma separated string of allowed domains. schema: type: string creationdate: name: creationdate in: query description: Creation date of the registration. schema: type: string officer: name: officer in: query description: Officer who signed the request. schema: type: string searchLimit: name: searchLimit in: query description: | The maximum number of certificates that should be returned. Please note that the highest possible value is still limited by server-side configuration (`certsearch.maxhits` in `cm.conf`). schema: type: integer searchOffset: name: searchOffset in: query description: | The starting offset of the first certificate that should be returned. This may be used for pagination of the results, together with the searchLimit parameter. schema: type: integer certificateSerialNumber: name: certificateSerialNumber in: query description: Serial number of the certificate. schema: type: string revocationTimeFrom: name: revocationTimeFrom in: query description: | Only return certificates whose revocation time is after the provided time. schema: type: string format: date-time revocationTimeTo: name: revocationTimeTo in: query description: | Only return certificates whose revocation time is before the provided time. schema: type: string format: date-time revocationReason: name: revocationReason in: query description: | Only return certificates with specified revocation reasons. Takes an array of integers in the format e.g. `1,2,3,4`. Reason code mapping: * 0: Unspecified * 1: Key Compromise * 2: Ca Compromise * 3: Affiliation Changed * 4: Superseded * 5: Cessation Of Operation * 6: Certificate Hold * 8: Remove From CRL * 9: Privilege Withdrawn * 10: AACompromise schema: type: array items: type: integer minimum: 0 maximum: 10 isNotRevoked: name: isNotRevoked in: query description: | If `true`, only certificates that are not revoked will be returned. schema: type: boolean publicationAllowed: name: publicationAllowed in: query description: | If `true`, only certificates where publication is allowed will be returned. schema: type: boolean publicationTimeFrom: name: publicationTimeFrom in: query description: | Only return certificates whose publication time is after the provided time. schema: type: string format: date-time publicationTimeTo: name: publicationTimeTo in: query description: | Only return certificates whose publication time is before the provided time. schema: type: string format: date-time ocspActivationTimeFrom: name: ocspActivationTimeFrom in: query description: | Only return certificates whose OCSP-activation time is after the provided time. schema: type: string format: date-time ocspActivationTimeTo: name: ocspActivationTimeTo in: query description: | Only return certificates whose OCSP-activation time is before the provided time. schema: type: string format: date-time validFromTimeFrom: name: validFromTimeFrom in: query description: | Only return certificates whose "valid from" (also named "not before") is after the provided time. schema: type: string format: date-time validFromTimeTo: name: validFromTimeTo in: query description: | Only return certificates whose "valid from" (also named "not before") is before the provided time. schema: type: string format: date-time isNotYetValid: name: isNotYetValid in: query description: | If `true`, only certificates whose "valid from" (also named "not before") is in the future will be returned. schema: type: boolean validToTimeFrom: name: validToTimeFrom in: query description: | Only return certificates whose "valid to (also named "not after") is after the provided time. schema: type: string format: date-time validToTimeTo: name: validToTimeTo in: query description: | Only return certificates whose "valid to" (also named "not after") is before the provided time. schema: type: string format: date-time isExpired: name: isExpired in: query description: | If `true`, only certificates that have already expired will be returned. This implies that the certificate's "valid to" (also named "not after") has passed. schema: type: boolean field1: name: field1 in: query description: | Only return certificates with the specified extended certificate search field set schema: type: string field2: name: field2 in: query description: | Only return certificates with the specified extended certificate search field set schema: type: string field3: name: field3 in: query description: | Only return certificates with the specified extended certificate search field set schema: type: string field4: name: field4 in: query description: | Only return certificates with the specified extended certificate search field set schema: type: string field5: name: field5 in: query description: | Only return certificates with the specified extended certificate search field set schema: type: string field6: name: field6 in: query description: | Only return certificates with the specified extended certificate search field set schema: type: string authorityKeyIdentifier: name: authorityKeyIdentifier in: query description: | AKI to filter results on. Must be in hexadecimal format. Example: 4A3A887184A13B28 schema: type: string subjectKeyIdentifier: name: subjectKeyIdentifier in: query description: | SKI to filter results on. Must be in hexadecimal format. Example: 4A3A887184A13B28 schema: type: string subjectType: name: subjectType in: query description: | Allows for filtering on subject type. By default only End Entity (EE) certificates are returned. Available values are: * EE * CA Takes an array of string in the format e.g. 'EE,CA`. Enum mapping: * EE: End Entity * CA: Certificate Authority schema: type: array items: type: string # Defines common responses used by multiple PATHS responses: RegistrationPost200: description: OK - Registration was successful content: application/json: schema: $ref: "#/components/schemas/RegistrationResponsePostOrPut" example: registration: {'regid':'kplclzbq4KeoaS86KimttAUlXKw='} error: 0 msg: "Registration has been successful" RegistrationPost500: description: Error - Registration failed, invalid input parameters content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" example: error: -14 msg: "Code -14, Registration type not supported" RegistrationUpdate200: description: OK - The updated registration content: application/json: schema: $ref: "#/components/schemas/RegistrationResponsePostOrPut" example: registration: {'regid':'kplclzbq4KeoaS86KimttAUlXKw='} error: 0 msg: "Registration has been successful" RegistrationUpdate500: description: Error - Registration update failed, no such registration content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" example: error: -14 msg: "Code -14, Registration type not supported" ServerError: description: Internal server error - An unexpected error occurred. content: application/json: schema: $ref: "#/components/schemas/ApiErrorResponse" example: error: -14 msg: "Code -14, Internal bad request"