swagger: "2.0"
info:
  title: The Giant Swarm API v4
  description: |
    This is the documentation for the Giant Swarm API starting at version `v4`.

    For an introduction to Giant Swarm, refer to the [documentation site](https://docs.giantswarm.io/).

    The Giant Swarm API attempts to behave in a __restful__ way. As a developer, you access resources using the `GET` method and, for example, delete them using the same path and the `DELETE` method.

    Accessing resources via GET usually returns all information available about a resource, while collections, like for example the list of all clusters you have access to, only contain a selected few attributes of each member item.

    Some requests, like for example the request to create a new cluster, don't return the resource itself. Instead, the response delivers a standard message body, showing a `code` and a `message` part. The `message` contains information for you or a client's end user. The `code` attribute contains some string (example: `RESOURCE_CREATED`) that is supposed to give you details on the state of the operation, in addition to standard HTTP status codes. This message format is also used in the case of errors. We provide a [list of all response codes](https://github.com/giantswarm/api-spec/blob/master/details/RESPONSE_CODES.md) outside this documentation.

    Feedback on the API as well as this documentation is welcome via `support@giantswarm.io` or on IRC channel [#giantswarm](irc://irc.freenode.org:6667/#giantswarm) on freenode.

    ## Source

    The source of this documentation is available on [GitHub](https://github.com/giantswarm/api-spec).

  termsOfService: https://giantswarm.io/terms/
  version: 4.0.0
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
consumes:
  - application/json
produces:
  - application/json
tags:
  - name: auth tokens
    description: |
      Auth Tokens are your way of authenticating against this API. You can create one by passing your email and base64 encoded password to the create auth token endpoint. The auth token never expires, in case you want to invalidate it you need to delete it (logout).
  - name: clusters
    description: |
      Clusters are a central resource of the Giant Swarm API. As a user or team using Giant Swarm, you set up Kubernetes clusters to run your own workloads.

      The API currently provides operations to create and delete clusters, as well as list all available clusters and get details on specific clusters.
  - name: info
    description: Information about the Giant Swarm installation
  - name: key pairs
    description: A key pair is a unique combination of a X.509 certificate and a private key. Key pairs are used to access the Kubernetes API of a cluster, both using `kubectl` and any standard web browser.
    externalDocs:
      url: https://docs.giantswarm.io/guides/accessing-services-from-the-outside/
      description: "User guide: Accessing Pods and Services from the Outside"
  - name: organizations
    description: Organizations are groups of users who own resources like clusters.
  - name: users
    description: A user represents a person that should have access to the Giant Swarm API. Users can belong to many groups, and are identified by email address.
  - name: releases
    description: |
      A release is a software bundle that constitutes a cluster.

      Releases are identified by their
      [semantic version number](http://semver.org/) in the `MAJOR.MINOR.PATCH`
      format.

      A release provides _components_, like for example Kubernetes. For each
      release the contained components are listed. Changes in components are
      detailed in the _changelog_ of a release.
securityDefinitions:
  AuthorizationHeaderToken:
    description: |
      Clients authenticate by passing an auth token via the `Authorization`
      header with a value of the format `giantswarm <token>`. Auth tokens can be
      obtained using the [createAuthToken](#operation/createAuthToken)
      operation.
    type: apiKey
    name: Authorization
    in: header

security:
  - AuthorizationHeaderToken: []

paths:
  /v4/info/:
    get:
      operationId: getInfo
      tags:
        - info
      summary: Get information on the installation
      description: |
        Returns a set of details on the installation. The output varies based
        on the provider used in the installation.

        This information is useful for example when creating new cluster, to
        prevent creating clusters with more worker nodes than possible.

        ### Example for an AWS-based installation

        ```json
        {
          "general": {
            "installation_name": "shire",
            "provider": "aws",
            "datacenter": "eu-central-1"
          },
          "workers": {
            "count_per_cluster": {
              "max": 20,
              "default": 3
            },
            "instance_type": {
              "options": [
                "m3.medium", "m3.large", "m3.xlarge"
              ],
              "default": "m3.large"
            }
          }
        }
        ```

        ### Example for a KVM-based installation

        ```json
        {
          "general": {
            "installation_name": "isengard",
            "provider": "kvm",
            "datacenter": "string"
          },
          "workers": {
            "count_per_cluster": {
              "max": 8,
              "default": 3
            },
          }
        }
        ```
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
      responses:
        "200":
          description: Information
          schema:
            $ref: "./definitions.yaml#/definitions/V4InfoResponse"
          examples:
            application/json:
              {
                "general": {
                  "installation_name": "shire",
                  "provider": "aws",
                  "datacenter": "eu-central-1"
                },
                "workers": {
                  "count_per_cluster": {
                    "max": 20,
                    "default": 3
                  },
                  "instance_type": {
                    "options": [
                      "m3.medium", "m3.large", "m3.xlarge"
                    ],
                    "default": "m3.large"
                  }
                }
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        default:
          description: Error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"

  /v4/auth-tokens/:
    post:
      operationId: createAuthToken
      tags:
        - auth tokens
      summary: Create Auth Token (Login)
      description: |
        Creates a Auth Token for a given user. Must authenticate with email and password.
      parameters:
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - name: body
          in: body
          required: true
          description: Create Auth Token Request
          schema:
            $ref: 'definitions.yaml#/definitions/V4CreateAuthTokenRequest'
          x-examples:
            application/json:
              {
                "email": "developer@example.com",
                "password_base64": "cGFzc3dvcmQ="
              }
      responses:
        "200":
          description: Success
          schema:
            $ref: "./definitions.yaml#/definitions/V4CreateAuthTokenResponse"
          examples:
            application/json:
              {
                "auth_token": "e5239484-2299-41df-b901-d0568db7e3f9"
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"

    delete:
      operationId: deleteAuthToken
      tags:
        - auth tokens
      summary: Delete Auth Token (Logout)
      description: |
        Deletes the authentication token provided in the Authorization header. This effectively logs you out.
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
      responses:
        "200":
          description: Success
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_DELETED",
                "message": "The authentication token has been succesfully deleted."
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"

  /v4/users/:
    get:
      operationId: getUsers
      tags:
        - users
      summary: Get users
      description: |
        Returns a list of all users in the system. Currently this endpoint is only available to users with admin permissions.
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
      responses:
        "200":
          description: Success
          schema:
            type: array
            items:
              $ref: "./definitions.yaml#/definitions/V4UserListItem"
          examples:
            application/json:
              [
                {"email": "andy@example.com", "created": "2017-01-15T12:00:00Z", "expiry": "2019-01-15T00:00:00Z"},
                {"email": "bob@example.com", "created": "2017-02-15T12:30:00Z", "expiry": "2020-01-15T00:00:00Z"},
                {"email": "charles@example.com", "created": "2017-03-15T13:00:00Z", "expiry": "2021-01-15T00:00:00Z"}
              ]
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        default:
          description: Error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"

  /v4/user/:
    get:
      operationId: getCurrentUser
      tags:
        - users
      summary: Get current user
      description: |
        Returns details about the currently authenticated user
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
      responses:
        "200":
          description: Success
          schema:
            $ref: "./definitions.yaml#/definitions/V4UserListItem"
          examples:
            application/json:
             {"email": "andy@example.com", "created": "2017-01-15T12:00:00Z", "expiry": "2019-01-15T00:00:00Z"}
        "201":
          # Fake response added with expanded content of 200, to run test assertion, e.g. 200 <=> 201
          description: Success
          schema:
            type: object
            properties:
              email:
                type: string
                description: Email address of the user
              created:
                type: string
                description: The date and time that this account was created
              expiry:
                type: string
                description: The date and time when this account will expire
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        default:
          description: Error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"

  /v4/users/{email}/:
    get:
      operationId: getUser
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter"
      tags:
        - users
      summary: Get user
      description: |
        Returns details about a specific user
      responses:
        "200":
          description: Success
          schema:
            $ref: "./definitions.yaml#/definitions/V4UserListItem"
          examples:
            application/json:
              {"email": "andy@example.com", "created": "2017-01-15T12:00:00Z", "expiry": "2019-01-15T00:00:00Z"}
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        "404":
          description: User not found
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_NOT_FOUND",
                "message": "The user could not be found. (not found: user with email 'bob@example.com' could not be found)"
              }
        default:
          description: Error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"

    put:
      operationId: createUser
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter"
        - name: body
          in: body
          required: true
          description: User account details
          schema:
            $ref: "./definitions.yaml#/definitions/V4CreateUserRequest"
          x-examples:
            application/json:
              {
                "password": "cGFzc3dvcmQ=",
                "expiry": "2020-01-01T12:00:00.000Z"
              }
      tags:
        - users
      summary: Create user
      description: |
        Creates a users in the system. Currently this endpoint is only available to users with admin permissions.
      responses:
        "201":
          description: User created
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_CREATED",
                "message": "The user with email 'bob@example.com' has been created."
              }
        "400":
          description: User already exists
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_ALREADY_EXISTS",
                "message": "The user could not be created. (invalid input: email 'bob@example.com' already exists)"
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        default:
          description: Error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"

    delete:
      operationId: deleteUser
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/UserEmailPathParameter"
      tags:
        - users
      summary: Delete user
      description: |
        Deletes a users in the system. Currently this endpoint is only available
        to users with admin permissions.
      responses:
        "200":
          description: User deleted
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_DELETED",
                "message": "The user with email 'bob@example.com' has been deleted."
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        "404":
          description: User not found
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_NOT_FOUND",
                "message": "The user could not be deleted. (not found: user with email 'bob@example.com' could not be found)"
              }
        default:
          description: Error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"

  /v4/clusters/:
    get:
      operationId: getClusters
      tags:
        - clusters
      summary: Get clusters
      description: |
        This operation fetches a list of clusters.

        The result depends on the permissions of the user.
        A normal user will get all the clusters the user has access
        to, via organization membership.
        A user with admin permission will receive a list of all existing
        clusters.

        The result array items are sparse representations of the cluster objects.
        To fetch more details on a cluster, use the [getCluster](#operation/getCluster)
        operation.
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
      responses:
        "200":
          description: Success
          schema:
            type: array
            items:
              $ref: "./definitions.yaml#/definitions/V4ClusterListItem"
          examples:
            application/json:
              [
                {
                  "id": "g8s3o",
                  "create_date": "2017-06-08T12:31:47.215Z",
                  "name": "Staging Cluster",
                  "owner": "acme"
                },
                {
                  "id": "3dkr6",
                  "create_date": "2017-05-22T13:58:02.024Z",
                  "name": "Test Cluster",
                  "owner": "testorg"
                }
              ]
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        default:
          description: Error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
    post:
      operationId: addCluster
      tags:
        - clusters
      summary: Create cluster
      description: |
        This operation is used to create a new Kubernetes cluster for an
        organization. The desired configuration can be specified using the
        __cluster definition format__ (see
        [external documentation](https://github.com/giantswarm/api-spec/blob/master/details/CLUSTER_DEFINITION.md)
        for details).

        The cluster definition format allows to set a number of optional
        configuration details, like memory size and number of CPU cores.
        However, one attribute is __mandatory__ upon creation: The `owner`
        attribute must carry the name of the organization the cluster will
        belong to. Note that the acting user must be a member of that
        organization in order to create a cluster.

        It is *recommended* to also specify the `name` attribute to give the
        cluster a friendly name, like e. g. "Development Cluster".

        Additional definition attributes can be used. Where attributes are
        omitted, default configuration values will be applied. For example, if
        no `release_version` is specified, the most recent version is used.

        The `workers` attribute, if present, must contain an array of node
        definition objects. The number of objects given determines the number
        of workers created.

        For example, requesting three worker nodes with default configuration
        can be achieved by submitting an array of three empty objects:

        ```"workers": [{}, {}, {}]```

        For clusters on AWS, note that all worker nodes must use the same instance type.

      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - name: body
          in: body
          required: true
          description: New cluster definition
          schema:
            $ref: "./definitions.yaml#/definitions/V4AddClusterRequest"
          x-examples:
            application/json:
              {
                "owner": "myteam",
                "release_version": "1.4.2",
                "name": "Example cluster with 3 default worker nodes",
                "workers": [{}, {}, {}]
              }
      responses:
        "201":
          description: Cluster created
          headers:
            Location:
              type: string
              description: URI to obtain details on the new cluster using the [getCluster](#operation/getCluster) operation
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_CREATED",
                "message": "A new cluster has been created with ID 'wqtlq'"
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        default:
          description: error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"

  /v4/clusters/{cluster_id}/:
    get:
      operationId: getCluster
      tags:
        - clusters
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
      summary: Get cluster details
      description: |
        This operation allows to obtain all available details on a particular cluster.
      responses:
        "200":
          description: Cluster details
          schema:
            $ref: "./definitions.yaml#/definitions/V4ClusterDetailsResponse"
          examples:
            application/json:
              {
                "id": "wqtlq",
                "create_date": "2017-03-03T10:50:45.949270905Z",
                "api_endpoint": "https://api.wqtlq.example.com",
                "name": "Just a Standard Cluster",
                "release_version": "2.5.16",
                "kubernetes_version": "",
                "owner": "acme",
                "workers": [
                  {
                    "memory": {"size_gb": 2.0},
                    "storage": {"size_gb": 20.0},
                    "cpu": {"cores": 4},
                    "labels": {
                      "beta.kubernetes.io/arch": "amd64",
                      "beta.kubernetes.io/os": "linux",
                      "ip": "10.3.11.2",
                      "kubernetes.io/hostname": "worker-1.x882ofna.k8s.gigantic.io",
                      "nodetype": "hicpu"
                    }
                  },
                  {
                    "memory": {"size_gb": 8.0},
                    "storage": {"size_gb": 20.0},
                    "cpu": {"cores": 2},
                    "labels": {
                      "beta.kubernetes.io/arch": "amd64",
                      "beta.kubernetes.io/os": "linux",
                      "ip": "10.3.62.2",
                      "kubernetes.io/hostname": "worker-2.x882ofna.k8s.gigantic.io",
                      "nodetype": "hiram"
                    }
                  }
                ],
                "kvm": {
                  "port_mappings": [
                    {
                      "port": 30020,
                      "protocol": "http"
                    },
                    {
                      "port": 30021,
                      "protocol": "https"
                    },
                  ]
                }
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        "404":
          description: Cluster not found
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_NOT_FOUND",
                "message": "The cluster with ID 'wqtlq' could not be found, or perhaps you do not have access to it. Please make sure the cluster ID is correct, and that you are a member of the organization that it belongs to."
              }
        default:
          description: error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
    patch:
      operationId: modifyCluster
      tags:
        - clusters
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - name: body
          in: body
          required: true
          description: Merge-patch body
          schema:
            $ref: "./definitions.yaml#/definitions/V4ModifyClusterRequest"
          x-examples:
            application/merge-patch+json:
              {
                "name": "New cluster name"
              }
        - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
      summary: Modify cluster
      description: |
        This operation allows to modify an existing cluster.

        A cluster modification is performed by submitting a `PATCH` request
        to the cluster resource (as described in the
        [addCluster](#operation/addCluster) and [getCluster](#operation/getCluster))
        in form of a [JSON Patch Merge
        (RFC 7386)](https://tools.ietf.org/html/rfc7386). This means, only the
        attributes to be modified have to be contained in the request body.

        The following attributes can be modified:

        - `name`: Rename the cluster to something more fitting.

        - `owner`: Changing the owner organization name means to change cluster
        ownership from one organization to another. The user performing the
        request has to be a member of both organizations.

        - `release_version`: By changing this attribute you can upgrade a
        cluster to a newer
        [release](https://docs.giantswarm.io/api/#tag/releases).

        - `workers`: By modifying the array of workers, nodes can be added to
        increase the cluster's capacity. See details below.

        ### Adding and Removing Worker Nodes (Scaling)

        Adding worker nodes to a cluster or removing worker nodes from a cluster
        works by submitting the `workers` attribute, which contains a (sparse)
        array of worker node defintions.

        _Sparse_ here means that all configuration details are optional. In the
        case that worker nodes are added to a cluster, wherever a configuration
        detail is missing, defaults will be applied. See
        [Creating a cluster](#operation/addCluster) for details.

        When modifying the cluster resource, you describe the desired state.
        For scaling, this means that the worker node array submitted must
        contain as many elements as the cluster should have worker nodes.
        If your cluster currently has five nodes and you submit a workers
        array with four elements, this means that one worker node will be removed.
        If your submitted workers array has six elements, this means one will
        be added.

        As an example, this request body could be used to scale a cluster to
        three worker nodes:

        ```json
        {
          "workers": [{}, {}, {}]
        }
        ```

        If the scaled cluster had four worker nodes before, one would be removed.
        If it had two worker nodes before, one with default settings would be
        added.

        ### Limitations

        - As of now, existing worker nodes cannot be modified.
        - When removing nodes (scaling down), it is not possible to determine
        which nodes will be removed.
        - On AWS based clusters, all worker nodes must use the same EC2 instance
        type (`instance_type` node attribute). By not setting an `instance_type`
        when submitting a PATCH request, you ensure that the right instance type
        is used automatically.

      responses:
        "200":
          description: Cluster modified
          schema:
            $ref: "./definitions.yaml#/definitions/V4ClusterDetailsResponse"
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        "404":
          description: Cluster not found
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_NOT_FOUND",
                "message": "The cluster with ID 'wqtlq' could not be found, or perhaps you do not have access to it. Please make sure the cluster ID is correct, and that you are a member of the organization that it belongs to."
              }
        default:
          description: error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
    delete:
      operationId: deleteCluster
      tags:
        - clusters
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
      summary: Delete cluster
      description: |
        This operation allows to delete a cluster.

        __Caution:__ Deleting a cluster causes the termination of all workloads running on the cluster. Data stored on the worker nodes will be lost. There is no way to undo this operation.

        The response is sent as soon as the request is validated.
        At that point, workloads might still be running on the cluster and may be accessible for a little wile, until the cluster is actually deleted.
      responses:
        "202":
          description: Deleting cluster
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_DELETION_STARTED",
                "message": "The cluster with ID 'wqtlq' is being deleted."
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        "404":
          description: Cluster not found
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_NOT_FOUND",
                "message": "The cluster with ID 'wqtlq' could not be found, or perhaps you do not have access to it. Please make sure the cluster ID is correct, and that you are a member of the organization that it belongs to."
              }
        default:
          description: error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"

  /v4/clusters/{cluster_id}/key-pairs/:
    get:
      operationId: getKeyPairs
      tags:
        - key pairs
      summary: Get key pairs
      description: |
        Returns a list of information on all key pairs of a cluster as an array.

        The individual array items contain metadata on the key pairs, but neither the key nor the certificate. These can only be obtained upon creation, using the [addKeypair](#operation/addKeyPair) operation.
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
      responses:
        "200":
          description: Key pairs
          schema:
            $ref: "./definitions.yaml#/definitions/V4GetKeyPairsResponse"
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        default:
          description: error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
    post:
      operationId: addKeyPair
      tags:
        - key pairs
      summary: Create key pair
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/ClusterIdPathParameter"
        - name: body
          in: body
          required: true
          description: |
            While the `ttl_hours` attribute is optional and will be set to a default value when omitted, the `description` is mandatory.
          schema:
            $ref: "./definitions.yaml#/definitions/V4AddKeyPairRequest"
          x-examples:
            application/json:
              {
                "description": "Admin key pair lasting twelve hours",
                "ttl_hours": 12,
                "certificate_organizations": "system:masters"
              }
      description: |
        This operation allows to create a new key pair for accessing a specific cluster.

        A key pair consists of an unencrypted private RSA key and an X.509 certificate. In addition, when obtaining a key pair for a cluster, the cluster's certificate authority file (CA certificate) is delivered, which is required by TLS clients to establish trust to the cluster.

        In addition to the credentials itself, a key pair has some metadata like a unique ID, a creation timestamp and a free text `description` that you can use at will, for example to note for whom a key pair has been issued.

        ### Customizing the certificate's subject for K8s RBAC

        It is possible to set the Common Name and Organization fields of the generated certificate's subject.

        - `cn_prefix`: The certificate's common name uses this format: `<cn_prefix>.user.<clusterdomain>`.

          `clusterdomain` is specific to your cluster and is not editable.

          The `cn_prefix` however is editable. When left blank it will default
          to the email address of the Giant Swarm user that is performing the
          create key pair request.

          The common name is used as the username for requests to the Kubernetes API. This allows you
          to set up role-based access controls.


        - `certificate_organizations`: This will set the certificate's `organization` fields. Use a comma separated list of values.
          The Kubernetes API will use these values as group memberships.

        __Note:__ The actual credentials coming with the key pair (key, certificate) can only be accessed once, as the result of the `POST` request that triggers their creation. This restriction exists to minimize the risk of credentials being leaked. If you fail to capture the credentials upon creation, you'll have to repeat the creation request.
      responses:
        "200":
          description: Success
          schema:
            $ref: "./definitions.yaml#/definitions/V4AddKeyPairResponse"
          examples:
            application/json:
              {
                "certificate_authority_data": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
                "client_key_data": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----",
                "client_certificate_data": "-----BEGIN CERTIFICATE-----...-----END CERTIFICATE-----",
                "create_date": "2016-06-01T12:00:00.000Z",
                "description": "Key pair description",
                "id": "02:cc:da:f9:fb:ce:c3:e5:e1:f6:27:d8:43:48:0d:37:4a:ee:b9:67",
                "ttl_hours": 8640
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"

  /v4/organizations/:
    get:
      operationId: getOrganizations
      tags:
        - organizations
      summary: Get organizations
      description: |
        This operation allows to fetch a list of organizations the user is a
        member of. In the case of an admin user, the result includes all
        existing organizations.
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
      responses:
        "200":
          description: Success
          schema:
            type: array
            items:
              $ref: "./definitions.yaml#/definitions/V4OrganizationListItem"
          examples:
            application/json:
              [
                {"id": "acme"},
                {"id": "giantswarm"},
                {"id": "testorg"}
              ]
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        default:
          description: Error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"

  /v4/organizations/{organization_id}/:
    get:
      operationId: getOrganization
      tags:
        - organizations
      summary: Get organization details
      description: |
        This operation fetches organization details.
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
      responses:
        "200":
          description: Organization details
          schema:
            $ref: "./definitions.yaml#/definitions/V4Organization"
          examples:
            application/json:
              {
                "id": "acme",
                "members": [
                  {"email": "user1@example.com"},
                  {"email": "user2@example.com"}
                ]
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        "404":
          description: Organization not found
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_NOT_FOUND",
                "message": "The organization could not be found. (not found: the organization with id 'acme' could not be found)"
              }
        default:
          description: Error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
    put:
      operationId: addOrganization
      tags:
        - organizations
      summary: Create an organization
      description: |
        This operation allows a user to create an organization.
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
        - name: body
          in: body
          required: true
          schema:
            $ref: "./definitions.yaml#/definitions/V4Organization"
          x-examples:
            application/json:
              {
                "id": "string",
                "members": [
                  {"email": "myself@example.com"},
                  {"email": "colleague@example.com"}
                ]
              }
      responses:
        "201":
          description: Organization created
          schema:
            $ref: "./definitions.yaml#/definitions/V4Organization"
          examples:
            application/json:
              {
                "id": "acme",
                "members": [
                  {"email": "user1@example.com"},
                  {"email": "user2@example.com"}
                ]
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        "409":
          description: Organization already exists
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_ALREADY_EXISTS",
                "message": "The organization could not be created. (org already exists)"
              }
        default:
          description: Error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
    patch:
      operationId: modifyOrganization
      tags:
        - organizations
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
        - name: body
          in: body
          required: true
          schema:
            type: object
            properties:
              members:
                type: array
                description: List of members that belong to this organization
                items:
                  $ref: "./definitions.yaml#/definitions/V4OrganizationMember"
          x-examples:
            application/merge-patch+json:
              {
                "members": [{"email": "myself@example.com"}]
              }

      summary: Modify organization
      description: |
        This operation allows you to modify an existing organization. You must be
        a member of the organization or an admin in order to use this endpoint.

        The following attributes can be modified:

        - `members`: By modifying the array of members, members can be added to or removed from the organization

        The request body must conform with the [JSON Patch Merge (RFC 7386)](https://tools.ietf.org/html/rfc7386) standard.
        Requests have to be sent with the `Content-Type: application/merge-patch+json` header.

        The full request must be valid before it will be executed, currently this
        means every member you attempt to add to the organization must actually
        exist in the system. If any member you attempt to add is invalid, the entire
        patch operation will fail, no members will be added or removed, and an error message
        will explain which members in your request are invalid.
      responses:
        "200":
          description: Organization modified
          schema:
            $ref: "./definitions.yaml#/definitions/V4Organization"
        "400":
          description: Invalid input
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "INVALID_INPUT",
                "message": "The organization could not be modified. (invalid input: user 'invalid-email' does not exist or is invalid)"
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        "404":
          description: Organization not found
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_NOT_FOUND",
                "message": "The organization could not be modified. (not found: the organization with id 'acme' could not be found)"
              }
        default:
          description: error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
    delete:
      operationId: deleteOrganization
      tags:
        - organizations
      summary: Delete an organization
      description: |
        This operation allows a user to delete an organization that they are a member of.
        Admin users can delete any organization.
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
      responses:
        "200":
          description: Organization deleted
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_DELETED",
                "message": "The organization with ID 'acme' has been deleted."
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        "404":
          description: Organization not found
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_NOT_FOUND",
                "message": "The organization could not be deleted. (not found: the organization with id 'acme' could not be found)"
              }
        default:
          description: Error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"

  /v4/organizations/{organization_id}/credentials/:
    post:
      operationId: addCredentials
      tags:
        - organizations
      summary: Set credentials
      description: |
        Add a set of credentials to the organization allowing the creation and
        operation of clusters within a cloud provider account/subscription.

        The actual type of these credentials depends on the cloud provider the
        installation is running on. Currently, only AWS is supported, with
        support for Azure being planned for the near future.

        Credentials in an organization are immutable. Each organization can only
        have one set of credentials.

        Once credentials have been set for an organization, they are used for
        every new cluster that will be created for the organization.

        ### Example request body for AWS

        ```json
        {
          "provider": "aws",
          "aws": {
            "roles": {
              "admin": "arn:aws:iam::123456789012:role/GiantSwarmAdmin",
              "awsoperator": "arn:aws:iam::123456789012:role/GiantSwarmAWSOperator"
            }
          }
        }
        ```
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
        - $ref: "./parameters.yaml#/parameters/OrganizationIdPathParameter"
        - name: body
          in: body
          required: true
          schema:
            $ref: "./definitions.yaml#/definitions/V4AddCredentialsRequest"
          x-examples:
            application/json:
              {
                "provider": "aws",
                "aws": {
                  "roles": {
                    "admin": "arn:aws:iam::123456789012:role/GiantSwarmAdmin",
                    "awsoperator": "arn:aws:iam::123456789012:role/GiantSwarmAWSOperator"
                  }
                }
              }
      responses:
        "201":
          description: Credentials created
          headers:
            Location:
              type: string
              description: URI of the new credentials resource
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_CREATED",
                "message": "A new set of credentials has been created with ID '5d9h4'"
              }
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"
        "409":
          description: Conflict
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"
          examples:
            application/json:
              {
                "code": "RESOURCE_ALREADY_EXISTS",
                "message": "The organisation already has a set of credentials"
              }
        default:
          description: error
          schema:
            $ref: "./definitions.yaml#/definitions/V4GenericResponse"

  /v4/releases/:
    get:
      operationId: getReleases
      tags:
        - releases
      summary: Get releases
      description: |
        Lists all releases available for new clusters or for upgrading existing
        clusters. Might also serve as an archive to obtain details on older
        releases.
      parameters:
        - $ref: './parameters.yaml#/parameters/RequiredGiantSwarmAuthorizationHeader'
        - $ref: './parameters.yaml#/parameters/XRequestIDHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmActivityHeader'
        - $ref: './parameters.yaml#/parameters/XGiantSwarmCmdLineHeader'
      responses:
        "200":
          description: Releases list
          schema:
            type: array
            items:
              $ref: "./definitions.yaml#/definitions/V4ReleaseListItem"
          examples:
            application/json:
              [
                {
                  "version": "1.14.9",
                  "timestamp": "2017-09-21T08:14:03.37759Z",
                  "changelog": [
                    {
                      "component": "kubernetes",
                      "description": "Security fixes"
                    },
                    {
                      "component": "calico",
                      "description": "Security fixes"
                    }
                  ],
                  "components": [
                    {
                      "name": "kubernetes",
                      "version": "1.5.8"
                    },
                    {
                      "name": "calico",
                      "version": "0.9.1"
                    }
                  ],
                  "active": false
                },
                {
                  "version": "2.8.4",
                  "timestamp": "2017-11-11T12:24:56.59969Z",
                  "changelog": [
                    {
                      "component": "calico",
                      "description": "Bugfix"
                    }
                  ],
                  "components": [
                    {
                      "name": "kubernetes",
                      "version": "1.7.3"
                    },
                    {
                      "name": "calico",
                      "version": "1.1.1"
                    }
                  ],
                  "active": true
                }
              ]
        "401":
          $ref: "./responses.yaml#/responses/V4Generic401Response"