openapi: 3.0.3
info:
  title: Venafi firefly-ca API
  version: v1
  description: API to request signing of certificate requests
  contact:
    name: Venafi
servers:
  - url: /
tags:
  - name: Public
    description: Public APIs
paths:
  /v1/certificatesigningrequest:
    post:
      summary: request a signed certificate
      tags:
        - Public
      operationId: create-certificate-signing-request
      description:  |
        Submit a single certificate signing request from a
        client. A request _must_ include at least a PEM encoded X.509 certificate
        signing request that has been signed by the client's private key. A client
        may optionally request other certificate attributes that cannot be encoded
        inside a certificate signing request. These additional attributes may or
        may not be honored based on the server's configuration and authorization policy.
        Requests may be denied by the server following a authorization review.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/certificateSigningRequest'
        description: Request for signing certificate request
      responses:
        '200':
          description: signed certificate with a chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/certificateSigningRequestResponse'
        '400':
          description: bad input parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/certificateRequestError'
  /v1/certificaterequest:
    post:
      summary: request a signed certificate and private key
      tags:
        - Public
      operationId: create-certificate-request
      description: |
        Creates key pair based on the provided CreateCertificateRequest from the client.
        Uses the public key to create CSR, then signs the certificate and returns it back to the client together with the private key.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/certificateRequest'
        description: Request for certificate
      responses:
        '200':
          description: signed certificate request chain
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/certificateRequestResponse'
        '400':
          description: bad input parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/certificateRequestError'
components:
  schemas:
    certificateRequestError:
      type: object
      description: certificate (signing) request errors
      required:
        - error
      properties:
        error:
          type: string
          description: shorthand description of error
        error_description:
          type: string
          description: detailed description of error
    certificateSigningRequest:
      type: object
      description: the payload for an certificate signing request
      required:
        - request
        - policyName
      properties:
        request:
          type: string
          description: a single PEM encoded X.509 certificate signing request, which must be signed by the client's private key
        validityPeriod:
          type: string
          description: an optional field containing ISO8601 formatted duration the client wishes the resulting X.509 certificate is signed for. The specified Policy has same attribute, so the shorter duration will be used indeed
        policyName:
          type: string
          description: the name of the Policy which the client wishes to request against.
    certificateSigningRequestResponse:
      type: object
      description: signed certificate with a chain
      required:
        - certificateChain
      properties:
        certificateChain:
          description: signed certificate with a chain
          type: string
    certificateRequest:
      type: object
      description: the payload for an certificate request
      required:
        - subject
        - policyName
      properties:
        subject:
          $ref: '#/components/schemas/subject'
        altNames:
          $ref: '#/components/schemas/altNames'
        keyType:
          type: string
          description:  an optional field used to specify parameters for the public and private keys. The public key will be used to create the CSR which will be signed. The private key will be returned to the client together with the issued certificate.
        validityPeriod:
          type: string
          description: an optional field containing ISO8601 formatted duration the client wishes the resulting X.509 certificate is signed for. The specified Policy has same attribute, so the shorter duration will be used indeed
        policyName:
          type: string
          description: the name of the Policy which the client wishes to request against.
    subject:
      type: object
      x-examples:
        example-1:
          commonName: "localhost"
          organization: "Venafi, inc"
          locality: "Salt Lake City"
          state: "Utah"
          country: "US"
      description: Subject attributes used for certificate request
      properties:
        commonName:
          type: string
          description: The common name used for certificate request
        orgUnits:
          type: array
          items:
            type: string
          description: The org units used for certificate request
        organization:
          type: string
          description: The organization used for certificate request
        locality:
          type: string
          description: The locality used for certificate request
        state:
          type: string
          description: The state used for certificate request
        country:
          type: string
          description: The country used for certificate request
    altNames:
      type: object
      description: optional field used to specify desired subject alternate names for the issued certificate.
      properties:
        dnsNames:
          type: array
          items:
            type: string
        ipAddresses:
          type: array
          items:
            type: string
        emailAddresses:
          type: array
          items:
            type: string
        uris:
          type: array
          items:
            type: string
    certificateRequestResponse:
      type: object
      description: signed certificate with a chain
      required:
        - certificateChain
        - privateKey
      properties:
        certificateChain:
          description: signed certificate with a chain
          type: string
        privateKey:
          description: generated private key
  responses: {}