X-Road (NIIS) Token Certificates API

openapi: 3.2.0
info:
  title: X Road Global Token Certificates API
  version: 2.1.0
  contact:
    name: Nordic Institute for Interoperability Solutions (NIIS)
    url: https://github.com/nordic-institute/X-Road-development/#enhancement-requests-and-error-reports
    email: info@niis.org
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  description: 'Operations tagged token-certificates across 2 of this provider''s published API definitions: security-server-admin-openapi.yaml, x-road-global-security-server-admin-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/v1
  description: basepath for API v1
security:
- ApiKeyAuth: []
tags:
- name: token-certificates
paths:
  /token-certificates:
    post:
      tags:
      - token-certificates
      summary: import new certificate
      operationId: importCertificate
      description: 'Imports certificate to the system.


        This endpoint can also return metadata in the error response if the client for the certificate is not found. The metadata array contains the identifier of that client.'
      requestBody:
        description: certificate to import
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CertificateFile'
      responses:
        '201':
          description: certificate created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCertificate'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /token-certificates/{hash}:
    get:
      tags:
      - token-certificates
      summary: get certificate information
      operationId: getCertificate
      description: Administrator views certificate details.
      parameters:
      - in: path
        name: hash
        description: SHA-256 hash of the certificate
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 64
          pattern: ^[a-fA-F0-9]+
      responses:
        '200':
          description: token certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCertificate'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    delete:
      tags:
      - token-certificates
      summary: delete certificate
      operationId: deleteCertificate
      description: 'Administrator deletes the certificate.


        This endpoint can also return metadata in the error response if the certificate is not found. The metadata array contains the id of that certificate.'
      parameters:
      - in: path
        name: hash
        description: SHA-256 hash of the certificate
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 64
          pattern: ^[a-fA-F0-9]+
      responses:
        '204':
          description: deletion was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /token-certificates/{hash}/activate:
    put:
      tags:
      - token-certificates
      summary: activate certificate
      operationId: activateCertificate
      description: Administrator activates selected certificate.
      parameters:
      - in: path
        name: hash
        description: SHA-256 hash of the certificate
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 64
          pattern: ^[a-fA-F0-9]+
      responses:
        '204':
          description: request was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /token-certificates/{hash}/disable:
    put:
      tags:
      - token-certificates
      summary: deactivate certificate
      operationId: disableCertificate
      description: Administrator deactivates selected certificate.
      parameters:
      - in: path
        name: hash
        description: SHA-256 hash of the certificate
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 64
          pattern: ^[a-fA-F0-9]+
      responses:
        '204':
          description: certificate was deactivated
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /token-certificates/{hash}/import:
    post:
      tags:
      - token-certificates
      summary: import an existing certificate from a token by cert hash
      operationId: importCertificateFromToken
      description: 'Imports certificate from a token to the system.


        This endpoint can also return metadata in the error response if the client for this certificate is not found. The metadata contains the identifier of that client.'
      parameters:
      - in: path
        name: hash
        description: SHA-256 hash of the certificate
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 64
          pattern: ^[a-fA-F0-9]+
      responses:
        '201':
          description: the imported certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenCertificate'
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '409':
          description: an existing item already exists
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /token-certificates/{hash}/possible-actions:
    get:
      tags:
      - token-certificates
      summary: get possible actions for one certificate
      operationId: getPossibleActionsForCertificate
      description: UI needs to know which actions can be done on one certificate.
      parameters:
      - in: path
        name: hash
        description: SHA-256 hash of the certificate
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 64
          pattern: ^[a-fA-F0-9]+
      responses:
        '200':
          description: possible actions that can be done on the certificate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PossibleActions'
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /token-certificates/{hash}/register:
    put:
      tags:
      - token-certificates
      summary: register certificate
      operationId: registerCertificate
      description: Administrator registers selected certificate.
      parameters:
      - in: path
        name: hash
        description: SHA-256 hash of the certificate
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 64
          pattern: ^[a-fA-F0-9]+
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SecurityServerAddress'
      responses:
        '200':
          description: request was successful
        '400':
          description: request was invalid
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
    servers:
    - url: /api/v1
      description: basepath for API v1
  /token-certificates/{hash}/unregister:
    put:
      tags:
      - token-certificates
      summary: unregister authentication certificate
      operationId: unregisterAuthCertificate
      description: 'Administrator unregisters selected authentication certificate.


        This endpoint can also return metadata in the error response if sending the management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.'
      parameters:
      - in: path
        name: hash
        description: SHA-256 hash of the certificate
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 64
          pattern: ^[a-fA-F0-9]+
      responses:
        '204':
          description: request was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
    servers:
    - url: /api/v1
      description: basepath for API v1
  /token-certificates/{hash}/mark-for-deletion:
    put:
      tags:
      - token-certificates
      summary: marks an auth certificate for deletion
      operationId: markAuthCertForDeletion
      description: 'Administrator marks an auth certificate for deletion.


        This endpoint can also return metadata in the error response if sending the management request fails. The metadata array contains the error details that were generated in core. The message is in plain English.'
      parameters:
      - in: path
        name: hash
        description: SHA-256 hash of the certificate
        required: true
        schema:
          type: string
          format: text
          minLength: 1
          maxLength: 64
          pattern: ^[a-fA-F0-9]+
      responses:
        '204':
          description: request was successful
        '400':
          description: request was invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_response:
                  $ref: '#/components/examples/ErrorExample'
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
        '401':
          description: authentication credentials are missing
        '403':
          description: request has been refused
        '404':
          description: resource requested does not exists
        '406':
          description: request specified an invalid format
        '500':
          description: internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorInfo'
              examples:
                error_metadata_response:
                  $ref: '#/components/examples/ErrorWithMetadataExample'
    servers:
    - url: /api/v1
      description: basepath for API v1
components:
  schemas:
    SecurityServerAddress:
      type: object
      required:
      - address
      properties:
        address:
          type: string
          description: Security server's IP address or DNS name
          format: text
          minLength: 1
          maxLength: 255
      example:
        address: 127.0.0.1
    TokenCertificate:
      type: object
      description: Certificate that is stored in a Token (auth or sign cert). Also includes the possible actions that can be done to this object, e.g DELETE (only for cert related operations and does not consider user authorization).
      required:
      - ocsp_status
      - owner_id
      - active
      - saved_to_configuration
      - certificate_details
      - status
      properties:
        ocsp_status:
          $ref: '#/components/schemas/CertificateOcspStatus'
        owner_id:
          type: string
          format: text
          description: client id of the owner member, <instance_id>:<member_class>:<member_code>
          example: FI:GOV:123
          minLength: 1
          maxLength: 767
          readOnly: true
        active:
          type: boolean
          description: if the certificate is active
          example: true
        saved_to_configuration:
          type: boolean
          description: if the certificate is saved to configuration
          example: true
        renewed_cert_hash:
          type: string
          format: text
          description: hash of the newer version of the certificate that is in the process of registration
          readOnly: true
        renewal_error:
          type: string
          format: text
          description: error message thrown during the certificate automatic renewal process
          readOnly: true
        ocsp_verify_before_activation_error:
          type: string
          format: text
          description: error message thrown when verifying ocsp responses before the certificate activation
          readOnly: true
        next_automatic_renewal_time:
          type: string
          format: date-time
          description: next planned automatic renewal time
          readOnly: true
        certificate_details:
          $ref: '#/components/schemas/CertificateDetails'
        status:
          $ref: '#/components/schemas/CertificateStatus'
        possible_actions:
          $ref: '#/components/schemas/PossibleActions'
    CertificateFile:
      type: object
      description: certificate file
      properties:
        certificate:
          description: the certificate file
          format: binary
          type: string
      required:
      - certificate
    CertificateDetails:
      type: object
      description: certificate details for any kind of certificate (TLS, auth, sign)
      required:
      - issuer_distinguished_name
      - issuer_common_name
      - subject_distinguished_name
      - subject_common_name
      - not_before
      - not_after
      - serial
      - version
      - signature_algorithm
      - signature
      - public_key_algorithm
      - rsa_public_key_modulus
      - rsa_public_key_exponent
      - hash
      - key_usages
      - subject_alternative_names
      properties:
        issuer_distinguished_name:
          type: string
          format: text
          description: certificate issuer distinguished name
          example: issuer123
          minLength: 1
          maxLength: 255
        issuer_common_name:
          type: string
          format: text
          description: certificate issuer common name
          example: domain.com
          minLength: 1
          maxLength: 255
        subject_distinguished_name:
          type: string
          format: text
          description: certificate subject distinguished name
          example: subject123
          minLength: 1
          maxLength: 255
        subject_common_name:
          type: string
          format: text
          description: certificate subject common name
          example: domain.com
          minLength: 1
          maxLength: 255
        not_before:
          type: string
          format: date-time
          description: certificate validity not before
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        not_after:
          type: string
          format: date-time
          description: certificate validity not after
          example: '2018-12-15T00:00:00.001Z'
          minLength: 24
          maxLength: 24
        serial:
          type: string
          format: text
          description: serial number
          example: '123456789'
          minLength: 1
          maxLength: 255
        version:
          type: integer
          format: int32
          example: 3
          description: version
        signature_algorithm:
          type: string
          format: sha-256
          description: certificate signature algorithm
          example: sha256WithRSAEncryption
          minLength: 1
          maxLength: 255
        signature:
          type: string
          format: text
          description: hex encoded certificate signature
          example: 30af2fdc1780...
          minLength: 1
          maxLength: 255
        public_key_algorithm:
          type: string
          format: sha-256
          description: certificate public key algorithm
          example: sha256WithRSAEncryption
          minLength: 1
          maxLength: 255
        rsa_public_key_modulus:
          type: string
          format: hex
          description: hex encoded RSA public key modulus (if RSA key)
          example: c44421d601...
          minLength: 1
          maxLength: 1000
        rsa_public_key_exponent:
          type: integer
          format: int32
          description: RSA public key exponent (if RSA key) as an integer
          example: 65537
        ec_public_parameters:
          description: EC public key curve (if EC key)
          example: secp256r1(1.2.840.10045.3.1.7)
          format: text
          maxLength: 255
          minLength: 1
          type: string
        ec_public_key_point:
          description: hex encoded EC public key point (if EC key)
          example: c44421d601...
          format: hex
          maxLength: 1000
          minLength: 1
          type: string
        hash:
          type: string
          format: text
          description: certificate SHA-256 hash
          example: 1234567890ABCDEF
          minLength: 1
          maxLength: 64
        key_usages:
          type: array
          description: certificate key usage array
          uniqueItems: true
          items:
            $ref: '#/components/schemas/KeyUsage'
        subject_alternative_names:
          type: string
          format: text
          description: certificate subject alternative names
          example: DNS:*.example.org
          minLength: 1
          maxLength: 1000
    KeyUsage:
      type: string
      description: certificate key usage
      example: NON_REPUDIATION
      enum:
      - DIGITAL_SIGNATURE
      - NON_REPUDIATION
      - KEY_ENCIPHERMENT
      - DATA_ENCIPHERMENT
      - KEY_AGREEMENT
      - KEY_CERT_SIGN
      - CRL_SIGN
      - ENCIPHER_ONLY
      - DECIPHER_ONLY
    PossibleActions:
      type: array
      description: array containing the possible actions that can be done for this item
      items:
        $ref: '#/components/schemas/PossibleAction'
    CertificateOcspStatus:
      type: string
      description: certificate status
      example: IN_USE
      enum:
      - DISABLED
      - EXPIRED
      - OCSP_RESPONSE_UNKNOWN
      - OCSP_RESPONSE_GOOD
      - OCSP_RESPONSE_SUSPENDED
      - OCSP_RESPONSE_REVOKED
    CertificateStatus:
      type: string
      description: certificate status
      example: IN_USE
      enum:
      - SAVED
      - REGISTRATION_IN_PROGRESS
      - REGISTERED
      - DELETION_IN_PROGRESS
      - GLOBAL_ERROR
    PossibleAction:
      type: string
      description: an action to change state or edit token, key, cert or csr
      example: DELETE
      enum:
      - DELETE
      - ACTIVATE
      - DISABLE
      - LOGIN
      - LOGOUT
      - REGISTER
      - UNREGISTER
      - IMPORT_FROM_TOKEN
      - GENERATE_KEY
      - EDIT_FRIENDLY_NAME
      - GENERATE_AUTH_CSR
      - GENERATE_SIGN_CSR
      - TOKEN_CHANGE_PIN
      - TOKEN_DELETE
    ErrorInfo:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/schemas/ErrorInfo
  examples:
    ErrorExample:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorExample
    ErrorWithMetadataExample:
      $ref: ../../../../../../common/common-admin-api/src/main/resources/common-openapi-definition.yaml#/components/examples/ErrorWithMetadataExample
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: X-Road-ApiKey token=<api key>
x-refined-from:
- security-server-admin-openapi.yaml
- x-road-global-security-server-admin-openapi.yml