Introduction

Hey there, and welcome to the official meshcloud API documentation! This documentation page will guide you through the process of integrating with our meshStack software. meshStack is our self-hosted software that you use to build your own meshcloud.

This API documentation will help you accomplish specific use cases that require you to read data from meshStack or insert data into meshStack.

meshStack offers various public REST endpoints to enable your use cases. If you’re interested in reading data from meshStack via a REST API, have a look at all API compatible meshObjects.

Providing or updating data into meshStack can be done via the meshObject Declarative Import API. As a leading cloud solution, we built this API with inspiration from the Kubernetes API, which is a declarative API that uses YML to represent its data. This API will feel familiar to those who have interacted with a Kubernetes cluster before. We also offer the ability to use JSON for those unfamiliar with YAML.

If you are not familiar with meshObjects, or the meshModel in general, we highly recommend reading about them in our public documentation. This should give you an idea of what the objects are, what their relationships are and when you need them.

Authentication

Before you start interacting with any of the endpoints we offer, make sure that you acquired valid HTTP Basic Auth credentials. We currently do not offer a personal authentication mechanism or self-service token generation for the API. This means only administrators with a valid Basic Auth token can currently make use of the meshstack API.

If you are an administrator and do not have valid credentials, please contact your meshcloud support via support@meshcloud.io

Each endpoint listed in the documentation is secured via HTTP Basic Auth. To authenticate requests, please set the Authorization header as such:

Authorization: Basic <base64 encoded username:password>

All endpoints are encrypted via SSL and can only be called via HTTPS.

Technical Specification

This section describes technical details of the meshStack API, such as the exact data types it provides or HTTP specifics.

HTTP verbs

meshStack tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

PUT

Used to update an existing resource, full updates only

DELETE

Used to delete an existing resource

HTTP status codes

meshStack tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

200 OK

Standard response for successful HTTP requests.
The actual response will depend on the request method used.
In a GET request, the response will contain an entity corresponding to the requested resource.
In a POST request, the response will contain an entity describing or containing the result of the action.

201 Created

The request has been fulfilled and resulted in a new resource being created.

204 No Content

The server successfully processed the request, but is not returning any content.

400 Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

401 Unauthorized

The server cannot authorize the request. Check the Basic Auth credentials used for the request.

403 Forbidden

The request is not allowed for the authorized user.

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

409 Conflict

The request leads to a conflict. A resource or a unique identifier used in the request already exists.

Data Types

  • Dates are always handled as UTC dates and formatted to ISO 8601 standard (e.g. 2020-12-22T09:37:43Z).

  • String fields are usually limited to 255 characters

Hypermedia

meshStack uses hypermedia. Resources include links to other resources in their responses. Responses are in Hypertext Application Language (HAL) format. Links can be found beneath the _links key. Users of the API should not create URIs themselves, instead they should use the above-described links to navigate from resource to resource.

Versioning

meshStack applies versioning via custom Media Types. This allows custom versioning per resource. As meshStack is developed and deployed continuously, this custom versioning per resource is the best way for applying versioning. If e.g. the meshCustomer response is modified in an incompatible way, a new version will be provided for meshCustomers and all other resources are untouched.

If using a request body, such as when inserting a new meshProject via a POST endpoint, the custom media type must be provided in the Content-Type header. In case of a response body, such as when requesting a list of all meshCustomers via a GET endpoint, the client should send the custom media type in the Accept header.

Examples for these headers are:

Accept: application/vnd.meshcloud.api.meshcustomer.v1.hal+json
Content-Type: application/vnd.meshcloud.api.meshobjectcollection.v1+json;charset=UTF-8

Which Media Type is required for which resource is described in the according Resource section. If a request body is required and a different Content-Type like simple application/json is requested, the endpoint will return an error.

If the Accept header is not provided, you may get the response of any version. Therefore please always provide the Accept header so you are guaranteed to get the resource in the expected format.

Common Data Formats

This section describes common data formats that are used across different endpoints.

Paging

Paged list endpoints support two request parameters for pagination, page and size.

Parameter Description

page

The number of the page you want to retrieve (default=0).

size

The amount of elements in a single page (default=50). Note: You can size up to 250. Greater values will be automatically lowered to this value.

Responses are structured like the following snippet:

{
    "_embedded": { }
    "_links": {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers"
        },
        "first" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers?page=0&size=20"
        },
        "prev" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers?page=0&size=20"
        },
        "next" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers?page=2&size=20"
        },
        "last" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers?page=3&size=20"
        }
    }
    "page": {
        "size": 20,
        "totalElements": 64,
        "totalPages": 4,
        "number": 0
    }
}

The above example is taken from the meshCustomer list endpoint. All relevant paging information is provided in the 'page' element. In addition to that the links to the first page, the next page (if exists), the previous page (if exists) and the last page are provided as well. Pagination links are only provided, if there is more than one page available for the given pagination parameters.

Tags

meshObjects can be tagged. The tags are provided as key/value pairs where the value is actually a list, as meshTags can also have multiple values.

An example could look like that:

"tags": {
    "environment": [
        "Dev",
        "QA"
    ],
    "confidentiality": [
        "Internal"
    ]
}

Resources

Index

This is the entry point to navigate through the API of meshStack. Starting from here you will be able to find all endpoints your authenticated user has access to.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Example Request
GET /api HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.v1.hal+json'
Response Fields
Path Type Description

_links

Object

All available Top-Level Links for the authenticated user.

Relation Description

metadata

The Metadata API to retrieve metadata from meshStack.

meshobjects

The MeshObjects API to get, create, update and delete meshObjects.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 257

{
  "_links" : {
    "meshobjects" : {
      "href" : "https://mesh-backend-url/api/meshobjects"
    },
    "metadata" : {
      "href" : "https://mesh-backend-url/api/metadata"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api"
    }
  }
}

meshObjects

Via this API you can get, create, update and delete meshObjects. For creating, updating and deleting meshObjects we currently only support a declarative way to do so. This is described in meshObject Declarative Import.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.metadata.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Example Request
GET /api/meshobjects HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshobjects.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshobjects.v1.hal+json'
Response Fields
Path Type Description

_links

Object

All available meshObject Links for the authenticated user.

Relation Description

meshcustomers

Get meshCustomers.

meshprojects

Get meshProjects.

meshtenants

Get meshTenants.

meshpaymentmethods

Get meshPaymentMethods.

meshusers

Get meshUsers.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshobjects.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 612

{
  "_links" : {
    "meshtenants" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants"
    },
    "meshcustomers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers"
    },
    "meshprojects" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
    },
    "meshpaymentmethods" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects"
    }
  }
}

meshCustomer

All endpoints on meshCustomers.

List meshCustomers

Provides a paged list of meshCustomers. Deleted meshCustomers are not provided via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshcustomer.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Request Parameters
Parameter Description

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.

Example Request
GET /api/meshobjects/meshcustomers?page=0&size=3 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshcustomer.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshcustomers?page=0&size=3' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshcustomer.v1.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshCustomers[]

Array

List of meshCustomer.

page

Object

See Paging information.

_links

Object

Currently only contains the self link and pagination links.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshcustomer.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 4083

{
  "_embedded" : {
    "meshCustomers" : [ {
      "apiVersion" : "v1",
      "kind" : "meshCustomer",
      "metadata" : {
        "name" : "admin-customer",
        "createdOn" : "2021-09-15T12:45:51Z"
      },
      "spec" : {
        "displayName" : "admin-customer",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers/admin-customer"
        },
        "meshtenants" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=admin-customer{&projectIdentifier,platformIdentifier}",
          "templated" : true
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=admin-customer"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=admin-customer{&projectIdentifier,platformIdentifier,customerRole,projectRole}",
          "templated" : true
        },
        "meshpaymentmethods" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=admin-customer"
        }
      }
    }, {
      "apiVersion" : "v1",
      "kind" : "meshCustomer",
      "metadata" : {
        "name" : "demo-customer",
        "createdOn" : "2021-09-15T12:45:51Z"
      },
      "spec" : {
        "displayName" : "demo-customer",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers/demo-customer"
        },
        "meshtenants" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=demo-customer{&projectIdentifier,platformIdentifier}",
          "templated" : true
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=demo-customer"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=demo-customer{&projectIdentifier,platformIdentifier,customerRole,projectRole}",
          "templated" : true
        },
        "meshpaymentmethods" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=demo-customer"
        }
      }
    }, {
      "apiVersion" : "v1",
      "kind" : "meshCustomer",
      "metadata" : {
        "name" : "demo-partner",
        "createdOn" : "2021-09-15T12:45:51Z"
      },
      "spec" : {
        "displayName" : "demo-partner",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers/demo-partner"
        },
        "meshtenants" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=demo-partner{&projectIdentifier,platformIdentifier}",
          "templated" : true
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=demo-partner"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=demo-partner{&projectIdentifier,platformIdentifier,customerRole,projectRole}",
          "templated" : true
        },
        "meshpaymentmethods" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=demo-partner"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers?page=0&size=3"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers?page=0&size=3"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers?page=1&size=3"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers?page=1&size=3"
    }
  },
  "page" : {
    "size" : 3,
    "totalElements" : 4,
    "totalPages" : 2,
    "number" : 0
  }
}
Get meshCustomer

Get a single meshCustomer. Deleted meshCustomers can also be requested via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshcustomer.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Example Request
GET /api/meshobjects/meshcustomers/admin-customer HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshcustomer.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshcustomers/admin-customer' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshcustomer.v1.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of meshCustomer datatype. Matches the version part provided within the Accept request header.

kind

String

As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshCustomer' for this endpoint.

metadata

Object

Always contains the 'name' to uniquely identify the meshCustomer. Can additionally contain meta information like the meshCustomer creation date.

metadata.name

String

The customerIdentifier as 'name' to uniquely identify the meshCustomer.

metadata.createdOn

String

The meshCustomer has been created at this date (e.g. 2020-12-22T09:37:43Z).

metadata.deletedOn

String

If the meshCustomer has already been deleted, the date when deletion happened is provided via this field. e.g. 2020-12-22T09:37:43Z

spec

Object

All fields in this section describe the meshCustomer.

spec.displayName

String

The display name of the meshCustomer as it is shown in meshPanel.

spec.tags

Object

Key/Value pairs of tags set on the meshCustomer. Keep in mind, that values are an array. Also see our general section about Tags

_links

Object

Available links [links] on a meshCustomer.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshcustomer.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1046

{
  "apiVersion" : "v1",
  "kind" : "meshCustomer",
  "metadata" : {
    "name" : "admin-customer",
    "createdOn" : "2021-09-15T12:45:51Z"
  },
  "spec" : {
    "displayName" : "admin-customer",
    "tags" : { }
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers/admin-customer"
    },
    "meshtenants" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=admin-customer{&projectIdentifier,platformIdentifier}",
      "templated" : true
    },
    "meshprojects" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=admin-customer"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=admin-customer{&projectIdentifier,platformIdentifier,customerRole,projectRole}",
      "templated" : true
    },
    "meshpaymentmethods" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=admin-customer"
    }
  }
}

meshProject

All endpoints on meshProjects.

List meshProjects

Provides a paged list of meshProjects. Deleted meshProjects are not provided via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshproject.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Request Parameters
Parameter Description

customerIdentifier

Filter for meshProjects that belong to the meshCustomer with given identifier. (optional)

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.

Example Request
GET /api/meshobjects/meshprojects?customerIdentifier=1s6o6mpds1&page=0&size=1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshproject.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=1s6o6mpds1&page=0&size=1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshproject.v1.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshProjects[]

Array

List of meshProject.

_links

Object

Currently only contains the self link and pagination links.

page

Object

See Paging information.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshproject.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1657

{
  "_embedded" : {
    "meshProjects" : [ {
      "apiVersion" : "v1",
      "kind" : "meshProject",
      "metadata" : {
        "name" : "test-project-1",
        "ownedByCustomer" : "1s6o6mpds1",
        "createdOn" : "2021-09-15T12:46:18.697353Z"
      },
      "spec" : {
        "displayName" : "Test Project 1",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects/1s6o6mpds1.test-project-1"
        },
        "meshtenants" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=1s6o6mpds1&projectIdentifier=test-project-1{&platformIdentifier}",
          "templated" : true
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=1s6o6mpds1&projectIdentifier=test-project-1{&platformIdentifier,customerRole,projectRole}",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=1s6o6mpds1&page=0&size=1"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=1s6o6mpds1&page=0&size=1"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=1s6o6mpds1&page=1&size=1"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=1s6o6mpds1&page=2&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 3,
    "totalPages" : 3,
    "number" : 0
  }
}
Get meshProject

Get a single meshProject. Deleted meshProjects can also be requested via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshproject.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Example Request
GET /api/meshobjects/meshprojects/1s6o6mpds1.test-project-1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshproject.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshprojects/1s6o6mpds1.test-project-1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshproject.v1.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of meshProject datatype. Matches the version part provided within the Accept request header.

kind

String

As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshProject' for this endpoint.

metadata

Object

Always contains the 'name' and 'ownedByCustomer' to uniquely identify the meshProject.

metadata.name

String

The projectIdentifier as 'name'.

metadata.ownedByCustomer

String

The customerIdentifier as 'ownedByCustomer'.

metadata.createdOn

String

The meshProject has been created at this date (e.g. 2020-12-22T09:37:43Z).

metadata.deletedOn

String

If the meshProject has already been deleted, the date when deletion happened is provided via this field. e.g. 2020-12-22T09:37:43Z

spec

Object

All fields in this section describe the meshProject.

spec.displayName

String

The display name of the meshProject as it is shown in meshPanel.

spec.tags

Object

Key/Value pairs of tags set on the meshProject. Keep in mind, that values are an array. Also see our general section about Tags

spec.paymentMethodIdentifier

String

The meshPaymentMethod of the meshProject.

spec.substitutePaymentMethodIdentifier

String

The substitutePaymentMethod of the meshProject

_links

Object

Available links [links] on a meshProject.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/vnd.meshcloud.api.meshproject.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 840

{
  "apiVersion" : "v1",
  "kind" : "meshProject",
  "metadata" : {
    "name" : "test-project-1",
    "ownedByCustomer" : "1s6o6mpds1",
    "createdOn" : "2021-09-15T12:46:18.697353Z"
  },
  "spec" : {
    "displayName" : "Test Project 1",
    "tags" : { }
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects/1s6o6mpds1.test-project-1"
    },
    "meshtenants" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=1s6o6mpds1&projectIdentifier=test-project-1{&platformIdentifier}",
      "templated" : true
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=1s6o6mpds1&projectIdentifier=test-project-1{&platformIdentifier,customerRole,projectRole}",
      "templated" : true
    }
  }
}

meshTenant

All endpoints on meshTenants.

List meshTenants

Provides a paged list of meshTenants. Deleted meshTenants are not provided via this endpoint.

Note: If a request parameter for filtering is not specified, all meshTenants are returned independently of that parameter.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshtenant.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Request Parameters
Parameter Description

customerIdentifier

Filter for meshTenants that belong to the meshCustomer with given identifier. (optional)

projectIdentifier

Filter for meshTenants that belong to the meshProject with given identifier. (optional)

platformIdentifier

Filter for meshTenants that belong to the meshPlatform with given identifier. (optional)

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.

Example Request
GET /api/meshobjects/meshtenants?customerIdentifier=test-customer&projectIdentifier=test-project&page=0&size=3 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshtenant.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=test-customer&projectIdentifier=test-project&page=0&size=3' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshtenant.v1.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshTenants[]

Array

List of meshTenant.

page

Object

See Paging information.

_links

Object

Currently only contains the self link and pagination links.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshtenant.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 3852

{
  "_embedded" : {
    "meshTenants" : [ {
      "apiVersion" : "v1",
      "kind" : "meshTenant",
      "metadata" : {
        "ownedByProject" : "test-project",
        "ownedByCustomer" : "test-customer",
        "platformIdentifier" : "azure.meshcloud-azure-dev",
        "assignedTags" : { }
      },
      "spec" : {
        "localId" : "2e662c48-7c2e-4aa6-9de3-513d7ff31409",
        "landingZone" : "stage-dev",
        "quotas" : [ {
          "key" : "limits.cpu",
          "value" : 2000
        }, {
          "key" : "limits.memory",
          "value" : 10000
        } ]
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/test-customer.test-project.azure.meshcloud-azure-dev"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=test-customer&projectIdentifier=test-project&platformIdentifier=azure.meshcloud-azure-dev{&customerRole,projectRole}",
          "templated" : true
        }
      }
    }, {
      "apiVersion" : "v1",
      "kind" : "meshTenant",
      "metadata" : {
        "ownedByProject" : "test-project",
        "ownedByCustomer" : "test-customer",
        "platformIdentifier" : "aws.aws-meshstack-dev",
        "assignedTags" : { }
      },
      "spec" : {
        "localId" : "d5bc65be-888b-462d-95f7-27d2d998e6d4",
        "landingZone" : "stage-dev",
        "quotas" : [ {
          "key" : "limits.cpu",
          "value" : 2000
        }, {
          "key" : "limits.memory",
          "value" : 10000
        } ]
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/test-customer.test-project.aws.aws-meshstack-dev"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=test-customer&projectIdentifier=test-project&platformIdentifier=aws.aws-meshstack-dev{&customerRole,projectRole}",
          "templated" : true
        }
      }
    }, {
      "apiVersion" : "v1",
      "kind" : "meshTenant",
      "metadata" : {
        "ownedByProject" : "test-project",
        "ownedByCustomer" : "test-customer",
        "platformIdentifier" : "okd4.openshift",
        "assignedTags" : { }
      },
      "spec" : {
        "localId" : "6a8805e3-3a59-4409-aac3-72a64f0c01b5",
        "landingZone" : "stage-dev",
        "quotas" : [ {
          "key" : "limits.cpu",
          "value" : 2000
        }, {
          "key" : "limits.memory",
          "value" : 10000
        } ]
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/test-customer.test-project.okd4.openshift"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=test-customer&projectIdentifier=test-project&platformIdentifier=okd4.openshift{&customerRole,projectRole}",
          "templated" : true
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=test-customer&projectIdentifier=test-project&page=0&size=3"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=test-customer&projectIdentifier=test-project&page=0&size=3"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=test-customer&projectIdentifier=test-project&page=1&size=3"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=test-customer&projectIdentifier=test-project&page=1&size=3"
    }
  },
  "page" : {
    "size" : 3,
    "totalElements" : 5,
    "totalPages" : 2,
    "number" : 0
  }
}
Get meshTenant

Get a single meshTenant. Deleted meshTenants are not provided via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshtenant.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Example Request
GET /api/meshobjects/meshtenants/test-customer.test-project.azure.meshcloud-azure-dev HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshtenant.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshtenants/test-customer.test-project.azure.meshcloud-azure-dev' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshtenant.v1.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of meshTenant datatype. Matches the version provided in the Accept request header.

kind

String

As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshTenant' for this endpoint.

metadata

Object

Always contains the 'ownedByProject', 'ownedByCustomer' and 'platformIdentifier' to identify the meshTenant.

metadata.ownedByProject

String

The identifier of the meshProject the meshTenant belongs to.

metadata.ownedByCustomer

String

The identifier of the meshCustomer the meshTenant belongs to.

metadata.platformIdentifier

String

The identifier of the related platform instance

metadata.assignedTags

Object

The tags assigned to this meshTenant originating from meshCustomer, Payment Method and meshProject. Keep in mind, that values are an array. Also see our general section about Tags

spec

Object

All fields in this section describe the meshTenant.

spec.localId

String

The localId (platform tenant id) assigned with this meshTenant. It will only be set if the tenant was either imported via meshObject API with a localId or if at least one replication run finished successfully for this tenant.

spec.landingZone

String

The Landing Zone of this meshTenant.

spec.quotas[]

Array

The set of applied Tenant Quotas. They can be set individually per tenant. By default the Landing Zone quotas are applied to new meshTenants.

_links

Object

Currently only contains the self link.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/vnd.meshcloud.api.meshtenant.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 899

{
  "apiVersion" : "v1",
  "kind" : "meshTenant",
  "metadata" : {
    "ownedByProject" : "test-project",
    "ownedByCustomer" : "test-customer",
    "platformIdentifier" : "azure.meshcloud-azure-dev",
    "assignedTags" : { }
  },
  "spec" : {
    "localId" : "2e662c48-7c2e-4aa6-9de3-513d7ff31409",
    "landingZone" : "stage-dev",
    "quotas" : [ {
      "key" : "limits.cpu",
      "value" : 2000
    }, {
      "key" : "limits.memory",
      "value" : 10000
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants/test-customer.test-project.azure.meshcloud-azure-dev"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=test-customer&projectIdentifier=test-project&platformIdentifier=azure.meshcloud-azure-dev{&customerRole,projectRole}",
      "templated" : true
    }
  }
}

meshPaymentMethod

All endpoints on meshPaymentMethods.

List meshPaymentMethods

Provides a paged list of meshPaymentMethods. Deleted meshPaymentMethods are not provided via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshpaymentmethod.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Request Parameters
Parameter Description

customerIdentifier

Filter for meshPaymentMethods that belong to the meshCustomer with given identifier. (optional)

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.

Example Request
GET /api/meshobjects/meshpaymentmethods?customerIdentifier=1s6o6mpmds1&page=0&size=2 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshpaymentmethod.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=1s6o6mpmds1&page=0&size=2' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshpaymentmethod.v1.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshPaymentMethods[]

Array

List of meshPaymentMethod.

_links

Object

Currently only contains the self link and pagination links.

page

Object

See Paging information.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshpaymentmethod.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1631

{
  "_embedded" : {
    "meshPaymentMethods" : [ {
      "apiVersion" : "v1",
      "kind" : "meshPaymentMethod",
      "metadata" : {
        "name" : "test-payment-method-1",
        "ownedByCustomer" : "1s6o6mpmds1"
      },
      "spec" : {
        "displayName" : "Test Payment Method 1",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment-method-1"
        }
      }
    }, {
      "apiVersion" : "v1",
      "kind" : "meshPaymentMethod",
      "metadata" : {
        "name" : "test-payment-method-2",
        "ownedByCustomer" : "1s6o6mpmds1"
      },
      "spec" : {
        "displayName" : "Test Payment Method 2",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment-method-2"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=1s6o6mpmds1&page=0&size=2"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=1s6o6mpmds1&page=0&size=2"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=1s6o6mpmds1&page=1&size=2"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=1s6o6mpmds1&page=1&size=2"
    }
  },
  "page" : {
    "size" : 2,
    "totalElements" : 3,
    "totalPages" : 2,
    "number" : 0
  }
}
Get meshPaymentMethod

Get a single meshPaymentMethod. Deleted meshPaymentMethods can also be requested via this endpoint.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshpaymentmethod.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Example Request
GET /api/meshobjects/meshpaymentmethods/test-payment-method-1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshpaymentmethod.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment-method-1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshpaymentmethod.v1.hal+json'
Response Fields
Path Type Description

apiVersion

String

Version of meshPaymentMethod datatype. Matches the version part provided within the Accept request header.

kind

String

As a common meshObject structure exists, every meshObject has a 'kind'. This is always 'meshPaymentMethod' for this endpoint.

metadata

Object

Always contains the 'name' and (optional) 'ownedByCustomer' to uniquely identify the meshPaymentMethod.

metadata.name

String

The paymentMethodIdentifier as 'name'.

metadata.ownedByCustomer

String

The customerIdentifier as 'ownedByCustomer'.

spec

Object

All fields in this section describe the meshPaymentMethod.

spec.displayName

String

The display name of the meshPaymentMethod as it is shown in meshPanel.

spec.tags

Object

Key/Value pairs of tags set on the meshPaymentMethod. Keep in mind, that values are an array. Also see our general section about Tags

spec.amount

String

The amount of the meshPaymentMethod.

spec.expirationDate

String

The expiration date date of the meshPaymentMethod.

_links

Object

Available links [links] on a meshPaymentMethod.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshpaymentmethod.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 375

{
  "apiVersion" : "v1",
  "kind" : "meshPaymentMethod",
  "metadata" : {
    "name" : "test-payment-method-1",
    "ownedByCustomer" : "1s6o6mpmds1"
  },
  "spec" : {
    "displayName" : "Test Payment Method 1",
    "tags" : { }
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment-method-1"
    }
  }
}

meshUser

All endpoints on meshUsers.

List meshUsers

Provides a paged list of meshUsers. Deleted meshUsers are not provided via this endpoint.

Note: If a request parameter for filtering is not specified, all active meshUsers are returned independently of that parameter. Filtering on projects with the projectIdentifier requires a customerIdentifier, as a projectIdentifier is only unique within a meshCustomer.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.meshuser.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Request Parameters
Parameter Description

customerIdentifier

Filter for meshUsers assigned to the meshCustomer with given identifier. (optional)

projectIdentifier

Requires customerIdentifier. Filter for meshUsers having access to the meshProject of a certain customer with given identifier. (optional)

platformIdentifier

Filter for meshUsers having access to a meshTenant which exist on the platform with given identifier. (optional)

customerRole

Filter for meshUsers with given customer role name, e.g Customer Admin. (optional)

projectRole

Filter for meshUsers with an active role by the given project role name. By default the following roles are used: Project Admin, Project User and Project Reader. (optional)

page

The page number (default=0). See Paging information.

size

The amount of elements in a single page (default=50). See Paging information.

Example Request
GET /api/meshobjects/meshusers?customerIdentifier=%20my-mobile-app-team&customerRole=Customer%20Admin&page=0&size=1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshuser.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=%20my-mobile-app-team&customerRole=Customer%20Admin&page=0&size=1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshuser.v1.hal+json'
Response Fields
Path Type Description

_embedded

Object

Contains the actual content of the paged response.

_embedded.meshUsers[]

Array

List of meshUser.

_links

Object

Currently only contains the self link and pagination links.

page

Object

See Paging information.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshuser.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1189

{
  "_embedded" : {
    "meshUsers" : [ {
      "apiVersion" : "v1",
      "kind" : "meshUser",
      "metadata" : {
        "name" : "john-doe"
      },
      "spec" : {
        "email" : "john-doe@example.com",
        "firstName" : "John",
        "lastName" : "Doe",
        "tags" : {
          "environment" : [ "dev", "test", "qa" ]
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=%20my-mobile-app-team&customerRole=Customer%20Admin&page=0&size=1"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=%20my-mobile-app-team&customerRole=Customer%20Admin&page=0&size=1"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=%20my-mobile-app-team&customerRole=Customer%20Admin&page=1&size=1"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerIdentifier=%20my-mobile-app-team&customerRole=Customer%20Admin&page=1&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 2,
    "totalPages" : 2,
    "number" : 0
  }
}

meshObject Declarative Import

To import existing cloud tenants to meshStack into existing company processes, meshStack provides an API to import meshObjects like meshCustomer, meshProject, etc.

The Declarative Import allows external systems to use a PUT request method for importing meshObject definitions within a YAML or JSON definition. All supported meshObjects can be found under Supported meshObjects.

meshObjects can be imported into a meshObjectCollection (Beta) using the following optional request parameters.

Request Headers
Name Description

Content-Type

meshObject Import is versioned and application/vnd.meshcloud.api.meshobjects.v1+yaml or application/vnd.meshcloud.api.meshobjects.v1+json can be used as a Content-Type.

Accept

meshObject Import is versioned and you should use application/vnd.meshcloud.api.meshobjects.v1+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Request Paramters
Parameter Description

meshObjectCollection

the name of the meshObjectCollection the meshObjects should be imported into (optional)

owner

If meshObjectCollection parameter is provided, this is the owner of the meshObjectCollection (optional)

Example Request in YAML
PUT /api/meshobjects?meshObjectCollection=collectionName&owner=ownerName HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshobjects.v1+yaml;charset=UTF-8
Accept: application/vnd.meshcloud.api.meshobjects.v1+json
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 407
Host: mesh-backend-url


apiVersion: v1
kind: meshUser
metadata:
  name: test-user
spec:
  email: test1-user@meshcloud.io
  firstName: test-user-first-name
  lastName: test-user-last-name
  euid: test-euid
---
apiVersion: v1
kind: meshCustomer
metadata:
  name: test-customer
spec:
  displayName: test-display-name
  costCenter: 1111
  tags:
    environment:
      - dev
      - qa
      - prod
    anotherTag:
      - myValue
Example Curl Request in YAML
$ curl 'https://mesh-backend-url/api/meshobjects?meshObjectCollection=collectionName&owner=ownerName' -i -u 'valid_username:valid_password' -X PUT \
    -H 'Content-Type: application/vnd.meshcloud.api.meshobjects.v1+yaml;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshobjects.v1+json' \
    -d '
apiVersion: v1
kind: meshUser
metadata:
  name: test-user
spec:
  email: test1-user@meshcloud.io
  firstName: test-user-first-name
  lastName: test-user-last-name
  euid: test-euid
---
apiVersion: v1
kind: meshCustomer
metadata:
  name: test-customer
spec:
  displayName: test-display-name
  costCenter: 1111
  tags:
    environment:
      - dev
      - qa
      - prod
    anotherTag:
      - myValue
    '
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshobjects.v1+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 272

[ {
  "meshObject" : "meshUser[test-user]",
  "status" : "SUCCESS",
  "resultCode" : null,
  "message" : null,
  "remarks" : null
}, {
  "meshObject" : "meshCustomer[test-customer]",
  "status" : "SUCCESS",
  "resultCode" : null,
  "message" : null,
  "remarks" : null
} ]
Response Fields
Path Type Description

[]

Array

An JSON array with meshObject import results containing the following fields per import result:

[].meshObject

String

The name of the meshObject.

[].status

String

The import result status for this meshObject. (SUCCESS or FAILED)

[].resultCode

String?

Specific result code for this import result.

Possible values: CUSTOMER_NOT_FOUND , PROJECT_NOT_FOUND

(might be null)

[].message

String?

A user readable message with more details. (might be null)

[].remarks

List<String>?

User readable remarks on this import result. (might be null)

Example Request
PUT /api/meshobjects?meshObjectCollection=collectionName&owner=ownerName HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshobjects.v1+json;charset=UTF-8
Accept: application/vnd.meshcloud.api.meshobjects.v1+json
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 650
Host: mesh-backend-url

[
  {
    "apiVersion": "v1",
    "kind": "meshUser",
    "metadata": {
      "name": "test-user"
    },
    "spec": {
      "email": "test1-user@meshcloud.io",
      "firstName": "test-user-first-name",
      "lastName": "test-user-last-name",
      "euid": "test-euid"
    }
  },
  {
    "apiVersion": "v1",
    "kind": "meshCustomer",
    "metadata": {
      "name": "test-customer"
    },
    "spec": {
      "displayName": "test-display-name",
      "costCenter": 1111,
      "tags": {
        "environment": [
          "dev",
          "qa",
          "prod"
        ],
        "anotherTag": [
          "myValue"
        ]
      }
    }
  }
]
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjects?meshObjectCollection=collectionName&owner=ownerName' -i -u 'valid_username:valid_password' -X PUT \
    -H 'Content-Type: application/vnd.meshcloud.api.meshobjects.v1+json;charset=UTF-8' \
    -H 'Accept: application/vnd.meshcloud.api.meshobjects.v1+json' \
    -d '[
  {
    "apiVersion": "v1",
    "kind": "meshUser",
    "metadata": {
      "name": "test-user"
    },
    "spec": {
      "email": "test1-user@meshcloud.io",
      "firstName": "test-user-first-name",
      "lastName": "test-user-last-name",
      "euid": "test-euid"
    }
  },
  {
    "apiVersion": "v1",
    "kind": "meshCustomer",
    "metadata": {
      "name": "test-customer"
    },
    "spec": {
      "displayName": "test-display-name",
      "costCenter": 1111,
      "tags": {
        "environment": [
          "dev",
          "qa",
          "prod"
        ],
        "anotherTag": [
          "myValue"
        ]
      }
    }
  }
]'
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.meshobjects.v1+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 272

[ {
  "meshObject" : "meshUser[test-user]",
  "status" : "SUCCESS",
  "resultCode" : null,
  "message" : null,
  "remarks" : null
}, {
  "meshObject" : "meshCustomer[test-customer]",
  "status" : "SUCCESS",
  "resultCode" : null,
  "message" : null,
  "remarks" : null
} ]

The following table lists all supported meshObjects. Declarative deletion means that a previously imported resource will be deleted, if it is not specified in a subsequent import. Declarative deletion only works, if the respective resource is part of a meshObjectCollection (Beta).

Supported meshObjects
Name Description Import Declarative Deletion

meshUser

user accounts

yes

no

meshCustomer

customer accounts

yes

no

meshPaymentMethod

payment methods

yes

no

meshProject

projects

yes

no

meshCustomerUserGroup

a user group

yes

yes

meshCustomerUserBinding

assigns users to customers

yes

no

meshCustomerGroupBinding

assigns groups to customers

yes

no

meshProjectUserBinding

assigns users to projects

yes

no

meshProjectGroupBinding

assigns groups to projects

yes

no

meshTenant

connects projects with platforms

yes

no

meshServiceInstance

a service instance

yes

no

meshServiceBinding

a service binding

yes

no

meshUser
YAML
apiVersion: v1
kind: meshUser
metadata:
  name: john-doe
spec:
  email: john.doe@example.com
  firstName: John
  lastName: Doe
  euid: john-doe-123 # External User Identifier, this is an optional field.
  tags: # optional field.
    environment:
      - dev
      - qa
      - prod
    anotherTag:
      - myValue
JSON
{
  "apiVersion": "v1",
  "kind": "meshUser",
  "metadata": {
    "name": "john-doe"
  },
  "spec": {
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "euid": "john-doe-123",
    "tags": {
      "environment": [
        "dev",
        "qa",
        "prod"
      ],
      "anotherTag": [
        "myValue"
      ]
    }
  }
}

If tags are provided on a meshUser, they should be consistent with tags defined on meshCustomerUserGroups, as meshUsers and meshCustomerUserGroups are handled as if they are the same. This is especially important when making use of meshPolicies on these two types of objects.

meshCustomer

See attribute definitions in GET endpoint section.

apiVersion: v1
kind: meshCustomer
metadata:
  name: my-mobile-app-team # this must be unique, so it can be used as a unique reference to the meshCustomer.
spec:
  displayName: Mobile App Team
  costCenter: 1111 # deprecated and optional field. Please use meshPaymentMethod import instead for cost center usage.
  tags:   # optional field
    environment:
      - dev
      - qa
      - prod
    anotherTag:
      - myValue
{
  "apiVersion": "v1",
  "kind": "meshCustomer",
  "metadata": {
    "name": "my-mobile-app-team"
  },
  "spec": {
    "displayName": "Mobile App Team",
    "costCenter": 1111,
    "tags": {
      "environment": [
        "dev",
        "qa",
        "prod"
      ],
      "anotherTag": [
        "myValue"
      ]
    }
  }
}
meshPaymentMethod

See attribute definitions in GET endpoint section. If you want to assign this payment method to a project, you can do so using the meshProject object.

apiVersion: v1
kind: meshPaymentMethod
metadata:
  name: mobile-app-budget-2021 # must be unique across entire meshstack
  ownedByCustomer: my-mobile-app-team
spec:
  displayName: Mobile App Budget 2021
  amount: 50000 #optional field, must be a number
  expirationDate: 2021-12-31 #optional field
  tags: #optional field
    costCenter:
      - 1332
    anotherTag:
      - myValue
      - someOtherValue
{
  "apiVersion": "v1",
  "kind": "meshPaymentMethod",
  "metadata": {
    "name": "mobile-app-budget-2021",
    "ownedByCustomer": "my-mobile-app-team"
  },
  "spec": {
    "displayName": "Mobile App Budget 2021",
    "amount": 50000,
    "expirationDate": "2021-12-31T00:00:00.000Z",
    "tags": {
      "costCenter": [
        1332
      ],
      "anotherTag": [
        "myValue",
        "someOtherValue"
      ]
    }
  }
}
meshProject

See attribute definitions in GET endpoint section.

apiVersion: v1
kind: meshProject
metadata:
  name: mobile-app-prod
  ownedByCustomer: my-mobile-app-team
spec:
  displayName: Mobile App Production
  tags: # optional field
    environment:
      - prod
  paymentMethodIdentifier: payment-id # optional field
  substitutePaymentMethodIdentifier: substitute-payment-id # optional field
{
  "apiVersion": "v1",
  "kind": "meshProject",
  "metadata": {
    "name": "mobile-app-prod",
    "ownedByCustomer": "my-mobile-app-team"
  },
  "spec": {
    "displayName": "Mobile App Production",
    "tags": {
      "environment": [
        "prod"
      ]
    },
    "paymentMethodIdentifier": "payment-id",
    "substitutePaymentMethodIdentifier": "substitute-payment-id"
  }
}

The optional payment method identifiers can be used to link the meshProject with meshPaymentMethods. If meshPaymentMethods are already assigned to an existing meshProject the assignments will be updated on meshProject re-import. It is not valid to specify only a substitutePaymentMethodIdentifier without defining a paymentMethodIdentifier.

meshCustomerUserGroup
apiVersion: v1
kind: meshCustomerUserGroup
metadata:
  name: my-user-group
  ownedByCustomer: my-mobile-app-team
spec:
  displayName: My User Group
  egid: sample-egid # External Group Identifier, this is an optional field.
  members: # list of usernames
    - john-doe
    - jane-doe
  tags: # optional field
    environment:
      - dev
      - qa
      - prod
    anotherTag:
      - myValue
{
  "apiVersion": "v1",
  "kind": "meshCustomerUserGroup",
  "metadata": {
    "name": "my-user-group",
    "ownedByCustomer": "my-mobile-app-team"
  },
  "spec": {
    "displayName": "My User Group",
    "egid": "sample-egid",
    "members": [
      "john-doe",
      "jane-doe"
    ],
    "tags": {
      "environment": [
        "dev",
        "qa",
        "prod"
      ],
      "anotherTag": [
        "myValue"
      ]
    }
  }
}
meshCustomerUserBinding
apiVersion: v1
kind: meshCustomerUserBinding
roleRef:
  name: Customer Admin
targetRef:
  name: my-mobile-app-team
subjects:
  - name: john-doe
  - name: jane-doe
{
  "apiVersion": "v1",
  "kind": "meshCustomerUserBinding",
  "roleRef": {
    "name": "Customer Admin"
  },
  "targetRef": {
    "name": "my-mobile-app-team"
  },
  "subjects": [
    {
      "name": "john-doe"
    },
    {
      "name": "jane-doe"
    }
  ]
}
meshCustomerGroupBinding

Assigns a meshCustomerUserGroup to a meshCustomer with the specified Role. All users in the group will receive the rights from the role. 4-eye-principle is not supported when creating a meshCustomerGroupBinding via this API.

apiVersion: v1
kind: meshCustomerGroupBinding
roleRef:
  name: Customer Admin
targetRef:
  name: my-mobile-app-team
subjects:
  - name: my-user-group
  - name: and-another-user-group
{
  "apiVersion": "v1",
  "kind": "meshCustomerGroupBinding",
  "roleRef": {
    "name": "Customer Admin"
  },
  "targetRef": {
    "name": "my-mobile-app-team"
  },
  "subjects": [
    {
      "name": "my-user-group"
    },
    {
      "name": "and-another-user-group"
    }
  ]
}
meshProjectUserBinding
apiVersion: v1
kind: meshProjectUserBinding
roleRef:
  name: Project Admin
targetRef:
  name: mobile-app-prod
  ownedByCustomer: my-mobile-app-team
subjects:
  - name: john-doe
  - name: jane-doe
{
  "apiVersion": "v1",
  "kind": "meshProjectUserBinding",
  "roleRef": {
    "name": "Project Admin"
  },
  "targetRef": {
    "name": "mobile-app-prod",
    "ownedByCustomer": "my-mobile-app-team"
  },
  "subjects": [
    {
      "name": "john-doe"
    },
    {
      "name": "jane-doe"
    }
  ]
}
meshProjectGroupBinding
apiVersion: v1
kind: meshProjectGroupBinding
roleRef:
  name: Project Employee
targetRef:
  name: mobile-app-prod
  ownedByCustomer: my-mobile-app-team
subjects:
  - name: my-user-group
  - name: and-another-user-group
{
  "apiVersion": "v1",
  "kind": "meshProjectGroupBinding",
  "roleRef": {
    "name": "Project Employee"
  },
  "targetRef": {
    "name": "mobile-app-prod",
    "ownedByCustomer": "my-mobile-app-team"
  },
  "subjects": [
    {
      "name": "my-user-group"
    },
    {
      "name": "and-another-user-group"
    }
  ]
}
meshTenant

See attribute definitions in GET endpoint section.

The localId property is optional. This means that a new tenant will be created within the specific platform if no localId was specified. The landingZone property may be skipped, e.g., for platforms that do not support landing zones.

The quotas must only contain keys that exist in the platform quota definitions for the respective platform, otherwise the import for the meshTenant will fail. Values of omitted quota keys defined in the platform quota definitions will be automatically set to the quotas of the specified landing zone.

apiVersion: v1
kind: meshTenant
metadata:
  ownedByProject: mobile-app-prod
  ownedByCustomer: my-mobile-app-team
  platformIdentifier: platform-identifier.location-identifier
spec:
  localId: test-tenant # (optional) The tenant id, e.g. AWS account id or Azure subscription id.
  landingZone: test-landing-zone # (optional) The landing zone name.
  quotas: # Only for platforms that support quotas
    - key: limits.cpu
      value: 2000
    - key: limits.memory
      value: 100000
{
  "apiVersion": "v1",
  "kind": "meshTenant",
  "metadata": {
    "ownedByProject": "mobile-app-prod",
    "ownedByCustomer": "my-mobile-app-team",
    "platformIdentifier": "platform-identifier.location-identifier"
  },
  "spec": {
    "localId": "test-tenant",
    "landingZone": "test-landing-zone",
    "quotas": [
      {
        "key": "limits.cpu",
        "value": 2000
      },
      {
        "key": "limits.memory",
        "value": 100000
      }
    ]
  }
}
meshServiceInstance
apiVersion: v1
kind: meshServiceInstance
metadata:
  ownedByProject: mobile-app-prod
  ownedByCustomer: my-mobile-app-team
  marketplaceIdentifier: global # You can find the marketplace identifier in the meshCustomer service brokers list in the meshPanel
  instanceId: f78ab615-75a4-446f-b8fe-a6db672c039a  # will be used when creating bindings (see meshServiceBinding example below)
spec:
  displayName: My Service Instance
  serviceId: 0164a5b6-f909-434b-9015-46939e993797
  planId: c6d93bf8-642c-48a7-a629-91869a5180c3
  creator: john-doe  # username of the user to use for creating the service instance
  parameters: # parameters may also be mitigated by providing an empty object: {}
    myParam: myValue
{
  "apiVersion": "v1",
  "kind": "meshServiceInstance",
  "metadata": {
    "ownedByProject": "mobile-app-prod",
    "ownedByCustomer": "my-mobile-app-team",
    "marketplaceIdentifier": "global",
    "instanceId": "f78ab615-75a4-446f-b8fe-a6db672c039a"
  },
  "spec": {
    "displayName": "My Service Instance",
    "serviceId": "0164a5b6-f909-434b-9015-46939e993797",
    "planId": "c6d93bf8-642c-48a7-a629-91869a5180c3",
    "creator": "john-doe",
    "parameters": {
      "myParam": "myValue"
    }
  }
}
meshServiceBinding
apiVersion: v1
kind: meshServiceInstanceBinding
metadata:
  ownedByServiceInstance: f78ab615-75a4-446f-b8fe-a6db672c039a
  bindingId: 32a3eb92-a210-48c4-b734-0b6f5874abc0
spec:
  displayName: My Service Instance Binding
  parameters: {}  # empty in this example
{
  "apiVersion": "v1",
  "kind": "meshServiceInstanceBinding",
  "metadata": {
    "ownedByServiceInstance": "f78ab615-75a4-446f-b8fe-a6db672c039a",
    "bindingId": "32a3eb92-a210-48c4-b734-0b6f5874abc0"
  },
  "spec": {
    "displayName": "My Service Instance Binding",
    "parameters": {}
  }
}

When binding to a tenant aware service you must also specify the tenant:

apiVersion: v1
kind: meshServiceInstanceBinding
metadata:
  ownedByServiceInstance: f78ab615-75a4-446f-b8fe-a6db672c039a
  bindingId: 32a3eb92-a210-48c4-b734-0b6f5874abc0
spec:
  displayName: My Binding With Tenant
  parameters:
    param: value
  tenant:
    localId: d4932d8f-2b31-4df7-be87-29a7ccd90a4d  # e.g. AWS account id or Azure subscription id
    platformIdentifier: aws.test-location
{
  "apiVersion": "v1",
  "kind": "meshServiceInstanceBinding",
  "metadata": {
    "ownedByServiceInstance": "f78ab615-75a4-446f-b8fe-a6db672c039a",
    "bindingId": "32a3eb92-a210-48c4-b734-0b6f5874abc0"
  },
  "spec": {
    "displayName": "My Binding With Tenant",
    "parameters": {
      "param": "value"
    },
    "tenant": {
      "localId": "d4932d8f-2b31-4df7-be87-29a7ccd90a4d",
      "platformIdentifier": "aws.test-location"
    }
  }
}

meshObjectCollection (Beta)

A meshObjectCollection can be used to group together meshObjects that are created via the meshObject Declarative Import. meshObjectCollections belong to one owner that is responsible to keep the meshObjectCollection updated. Modifications to any meshObjects from a meshObjectCollection can only be done by the specified owner via the meshObject API.

The createMeshObjectCollection endpoint must be called once to create a new meshObjectCollection before the meshObject API can assign meshObjects to it.

meshObjectCollections are currently in Beta state. As of now adding meshObjects to meshObjectCollections works using the meshObject API. Deletion will follow at a later stage.

createMeshObjectCollection

This endpoint will create a new empty meshObjectCollection.

Request Headers
Name Description

Content-Type

meshObjectCollections are versioned and currently only support application/vnd.meshcloud.api.meshobjectcollection.v1+json as a Content-Type.

Request Fields
Path Type Description

name

String

Name of the meshObjectCollection (has to be unique)

owner

String

The owner of the meshObjectCollection

description

String

A freetext field to help describing the contents of the meshObjectCollection

Example Request
POST /api/meshobjectcollections HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshobjectcollection.v1+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 150
Host: mesh-backend-url


      {
        "name": "collection-name",
        "owner": "collection-owner",
        "description": "This is a meshObjectCollection."
      }
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjectcollections' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/vnd.meshcloud.api.meshobjectcollection.v1+json;charset=UTF-8' \
    -d '
      {
        "name": "collection-name",
        "owner": "collection-owner",
        "description": "This is a meshObjectCollection."
      }
    '
Example Response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

deleteMeshObjectCollection

This endpoint can be used to delete an existing meshObjectCollection. It will not remove any meshObjects and works only for empty meshObjectCollections. To delete a meshObjectCollection and all assigned meshObjects, those have to be deleted manually before calling this endpoint.

Request Headers
Name Description

Content-Type

meshObjectCollections are versioned and currently only support application/vnd.meshcloud.api.meshobjectcollection.v1+json as a Content-Type.

Request Fields
Path Type Description

name

String

Name of the meshObjectCollection

owner

String

The owner of the meshObjectCollection

Example Request
DELETE /api/meshobjectcollections HTTP/1.1
Content-Type: application/vnd.meshcloud.api.meshobjectcollection.v1+json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 92
Host: mesh-backend-url


      {
        "name": "collection-name",
        "owner": "collection-owner"
      }
Example Curl Request
$ curl 'https://mesh-backend-url/api/meshobjectcollections' -i -u 'valid_username:valid_password' -X DELETE \
    -H 'Content-Type: application/vnd.meshcloud.api.meshobjectcollection.v1+json;charset=UTF-8' \
    -d '
      {
        "name": "collection-name",
        "owner": "collection-owner"
      }
    '
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Example Error Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 171

{
  "error" : "MeshBadRequestException",
  "message" : "MeshObjectCollection not-empty-collection cannot be deleted, because it is not empty",
  "errorId" : "WnfKT5DV3o"
}

Metadata

Cloud Platforms may want to enrich their tenant metadata with meshMetadata. This could e.g. be billing information. This metadata can be retrieved via the endpoints defined in this section.

Request Headers
Name Description

Accept

meshApi is versioned and you should use application/vnd.meshcloud.api.metadata.v1.hal+json as an Accept header to be guaranteed the V1 response format of this endpoint. New versions will be added in future.

Example Request
GET /api/metadata HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.metadata.v1.hal+json
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/api/metadata' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.metadata.v1.hal+json'
Response Fields
Path Type Description

_links

Object

All available Metadata Links for the authenticated user.

Relation Description

openstackProjectMetadata

Link to openStackProjectMetadata to retrieve metadata for tagging OpenStack resources.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/vnd.meshcloud.api.metadata.v1.hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 220

{
  "_links" : {
    "openstackProjectMetadata" : {
      "href" : "https://mesh-backend-url/api/metadata/openstackProjectMetadata"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/metadata"
    }
  }
}

openStackProjectMetadata

This endpoint returns metadata information for the requested project-id. This endpoint is based on OpenStack vendor data (https://docs.openstack.org/nova/rocky/user/vendordata.html).

Request Fields
Path Type Description

project-id

String

The ID of the project metadata information shall be retrieved for.

Example Request
POST /api/metadata/openstackProjectMetadata HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 82
Host: mesh-backend-url


      {
        "project-id": "d3fc4451-f555-44f2-b651-c8062d21d0e3"
      }
Example Curl Request
$ curl 'https://mesh-backend-url/api/metadata/openstackProjectMetadata' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '
      {
        "project-id": "d3fc4451-f555-44f2-b651-c8062d21d0e3"
      }
    '
Response Fields
Path Type Description

project-identifier

String

Immutable unique identifier of the project.

project-display-name

String

Human readable project name.

customer-identifier

String

Immutable unique identifier of the customer

customer-display-name

String

Human readable customer name.

tags

Object

Custom tags specified on the project.

tags.costCenter

Array

A cost center number could be a custom tag.

tags.customNumber

Array

And any further attribute can be provided as a tag.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 280

{
  "project-identifier" : "test-project-identifier",
  "project-display-name" : "test-project",
  "customer-identifier" : "test-customer-identifier",
  "customer-display-name" : "test-customer",
  "tags" : {
    "costCenter" : [ "1235" ],
    "customNumber" : [ "1645789" ]
  }
}

Workflow APIs (deprecated)

The endpoints listed below are legacy endpoints that we have officially deprecated. Whatever your needs are, please do not use these APIs! Use the existing meshObject APIs instead.

getUsers

This endpoint returns all available users mapped by a username and assigned customer identifiers.

Example Request
GET /external/users HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/external/users' -i -u 'valid_username:valid_password' -X GET
Response Fields
Path Type Description

[].username

String

The username of the user.

[].customerAccounts

Array

An array of customers the user is assigned to or an empty array.

[].customerAccounts[].identifier

String

An array of customers the user is assigned to or an empty array.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1622

[ {
  "username" : "admin@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "admin-customer"
  } ]
}, {
  "username" : "customer@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "demo-customer"
  } ]
}, {
  "username" : "customer-e@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "demo-customer"
  } ]
}, {
  "username" : "partner@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "demo-partner"
  }, {
    "identifier" : "managed-customer"
  } ]
}, {
  "username" : "partner-e@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "demo-partner"
  } ]
}, {
  "username" : "billing@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "admin-customer"
  } ]
}, {
  "username" : "managed@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "managed-customer"
  } ]
}, {
  "username" : "unassigned@meshcloud.io",
  "customerAccounts" : [ ]
}, {
  "username" : "platform-operator@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "demo-partner"
  } ]
}, {
  "username" : "controller@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "demo-partner"
  } ]
}, {
  "username" : "ops-support@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "demo-partner"
  } ]
}, {
  "username" : "onboarding-support@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "demo-partner"
  } ]
}, {
  "username" : "compliance@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "demo-partner"
  } ]
}, {
  "username" : "replication-operator@meshcloud.io",
  "customerAccounts" : [ {
    "identifier" : "demo-partner"
  } ]
} ]

getUserCustomers

As a user can be assigned to multiple customers in meshStack, the userId is not sufficient for creating a new limited payment method in meshStack, as payment methods always have to be assigned to a customer. This function allows the client to retrieve the list of all customers the user is assigned to and is allowed to create payment methods in.

/external/users/{username}/customers
Parameter Description

username

The username of the user to scope the customers.

Example Request
GET /external/users/managed@meshcloud.io/customers HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/external/users/managed@meshcloud.io/customers' -i -u 'valid_username:valid_password' -X GET
Response Fields
Path Type Description

customers

Array

List of all customers the user is assigned to and has the right to create payment methods in

customers[].name

String

Display Name of the customer.

customers[].identifier

String

Identifier of the customer.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 100

{
  "customers" : [ {
    "name" : "managed customer",
    "identifier" : "managed-customer"
  } ]
}

getCustomers

This endpoint allows the client to retrieve the list of all customers.

Example Request
GET /external/customers HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/external/customers' -i -u 'valid_username:valid_password' -X GET
Response Fields
Path Type Description

customers[]

Array

List of all customers.

customers[].identifier

String

Identifier of the customer.

customers[].displayName

String

Display Name of the customer.

customers[].contactPerson

Object

Contact Person with username and fullName or null.

customers[].contactPerson.username

String

Contact Person’s' username.

customers[].contactPerson.fullName

String

Contact Person’s' fullName.

customers[].financialAdmins[]

Array

List of all user who are allowed to create payment methods.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 1032

{
  "customers" : [ {
    "identifier" : "admin-customer",
    "displayName" : "admin-customer",
    "contactPerson" : null,
    "financialAdmins" : [ ]
  }, {
    "identifier" : "demo-customer",
    "displayName" : "demo-customer",
    "contactPerson" : {
      "username" : "customer@meshcloud.io",
      "fullName" : "Meshcloud Demo Customer Admin (customer@meshcloud.io)"
    },
    "financialAdmins" : [ "customer@meshcloud.io" ]
  }, {
    "identifier" : "demo-partner",
    "displayName" : "demo-partner",
    "contactPerson" : {
      "username" : "partner@meshcloud.io",
      "fullName" : "Meshcloud Demo Partner Admin (partner@meshcloud.io)"
    },
    "financialAdmins" : [ "partner@meshcloud.io" ]
  }, {
    "identifier" : "managed-customer",
    "displayName" : "managed customer",
    "contactPerson" : {
      "username" : "managed@meshcloud.io",
      "fullName" : "Meshcloud Managed Customer Managed (managed@meshcloud.io)"
    },
    "financialAdmins" : [ "managed@meshcloud.io", "partner@meshcloud.io" ]
  } ]
}

createLimitedPaymentMethod

deprecated Refer to meshPaymentMethod imports via the meshObject Declarative Import

This endpoint allows external systems to create custom limited payment methods for customers.

/external/customers/{customerIdentifier}/limitedPaymentMethods/{paymentIdentifier}
Parameter Description

customerIdentifier

Defines the customer to which the payment method will be assigned.

paymentIdentifier

Defines an immutable payment identifier. Must be globally unique (e.g. use a GUID)

Request Fields
Path Type Description

name

String

Name of the Custom Payment. Must be unique per customer.

amount

Number

The maximum approved amount in EUR on this payment method for one budget year.

userId

String

The username requesting creation of the Custom Payment. This user must have an assigned 'Customer Admin' role on the Customer identified by customerIdentifier.This check helps prevent API consumers from acting as a 'confused deputy' on Customer Accounts.

expirationDate

String

Expiration date of the payment method (e.g. 2020-11-30)

customAttributes

Object

Further attributes that shall be set on the payment method. It is an array as key-value pairs where key is attribute name and value (as a string) is attribute value. Nested Objects are not supported.

customAttributes.example-attribute

String

An example attribute.

Example Request
PUT /external/customers/managed-customer/limitedPaymentMethods/payment-identifier HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 241
Host: mesh-backend-url


      {
        "name": "Custom Payment",
        "amount": 9500,
        "userId": "managed@meshcloud.io",
        "expirationDate": "2020-11-30",
        "customAttributes": {
          "example-attribute": "123456"
        }
      }
Example Curl Request
$ curl 'https://mesh-backend-url/external/customers/managed-customer/limitedPaymentMethods/payment-identifier' -i -u 'valid_username:valid_password' -X PUT \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '
      {
        "name": "Custom Payment",
        "amount": 9500,
        "userId": "managed@meshcloud.io",
        "expirationDate": "2020-11-30",
        "customAttributes": {
          "example-attribute": "123456"
        }
      }
    '
Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: text/plain;charset=UTF-8
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY

checkUserExistence

Every meshStack installation can be configured to either allow the creation of multiple customers for one user or not. The third-party tool used for registration can accordingly decide whether it prevents or allows creating multiple customers per user. The checkUserExistence endpoints executes the check whether a user already exists in the meshStack. If multiple customer creation is allowed, the third party tool may show an info like "You already created a meshCustomer! Do you really want to create another one?" to the user.

/external/registration/checkUserExistence/{username}
Parameter Description

username

The username of the user to be checked.

Example Request
GET /external/registration/checkUserExistence/customer@meshcloud.io HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/external/registration/checkUserExistence/customer@meshcloud.io' -i -u 'valid_username:valid_password' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'
Response Fields
Path Type Description

username

String

The username of the requested user.

exists

Boolean

Indicates whether a user exists or not.

customerAccounts

Array

An array of customer names the user is assigned to or an empty array.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Disposition: inline;filename=f.txt
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 105

{
  "username" : "customer@meshcloud.io",
  "exists" : true,
  "customerAccounts" : [ "demo-customer" ]
}

checkCostCenterExistence

Every meshStack installation can be configured to support costCenter assignments on customer and project level. From a company perspective you may want to avoid users from creating several customers for the same cost center. The checkCostCenterExistence allows third-party tools to check for the existence of a cost center in meshStack and e.g. show a warning to the user.

/external/registration/checkCostCenterExistence/{costCenter}
Parameter Description

costCenter

The costCenter to be checked for existence.

Example Request
GET /external/registration/checkCostCenterExistence/333 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Host: mesh-backend-url
Example Curl Request
$ curl 'https://mesh-backend-url/external/registration/checkCostCenterExistence/333' -i -u 'valid_username:valid_password' -X GET \
    -H 'Content-Type: application/json;charset=UTF-8'
Response Fields
Path Type Description

customers

Array

List of customers for the requested cost center or an empty list.

customers[].name

String

Name of the customer.

customers[].contactPerson

Object

The contact person of the customer.

customers[].contactPerson.username

String

Username of the customer’s contact person.

customers[].contactPerson.fullName

String

Full name of the customer’s contact person.

Example Response
HTTP/1.1 200 OK
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/hal+json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 184

{
  "customers" : [ {
    "name" : "demo-customer",
    "contactPerson" : {
      "username" : "customer@meshcloud.io",
      "fullName" : "Meshcloud Demo Customer Admin"
    }
  } ]
}

externalRegistration

Via this endpoint a new Customer can be created in meshStack. All information required for the creation is described in the following.

Request Fields
Path Type Description

username

String

Username of the user who creates the new meshCustomer. Often this is a LDAP ID or another company-wide username. (If this user is not yet available in meshStack, userDetails have to be provided.) This user will be assigned the 'Customer Owner' role on the newly created meshCustomer.

userDetails

Object

Details of the user who creates the new meshCustomer. (Can be omitted, if username of a user who is already available in meshStack is provided.)

userDetails.firstName

String

First name of the user.

userDetails.lastName

String

Last name of the user.

userDetails.email

String

Email of the user.

userDetails.euid

String

Optional external user identifier. It is used to identify the user in cloud platforms like Azure or Google, which are using their own user directory.

sourceSystem

String

Name of the third-party system that calls this endpoint.

customer

Object

Details about the customer, that shall be created.

customer.name

String

Name of the customer.

customer.identifier

String

Immutable unique identifier of the customer. Must be at max 16 chars long and match regex: ^[a-z0-9\-]+$

customer.costCenter

String

Cost Center the customer shall be assigned to.

Example Request
POST /external/registration HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Content-Length: 400
Host: mesh-backend-url

{
        "username": "1s6o6erds1",
        "userDetails": {
            "firstName": "Thomas",
            "lastName": "Tester",
            "email": "user-email",
            "euid": "test-euid"
        },
        "sourceSystem": "my-system",
        "customer": {
            "name": "Docs Test Customer",
            "identifier": "docs-tst-cstmr",
            "costCenter": "333"
        }
    }
Example Curl Request
$ curl 'https://mesh-backend-url/external/registration' -i -u 'valid_username:valid_password' -X POST \
    -H 'Content-Type: application/json;charset=UTF-8' \
    -d '{
        "username": "1s6o6erds1",
        "userDetails": {
            "firstName": "Thomas",
            "lastName": "Tester",
            "email": "user-email",
            "euid": "test-euid"
        },
        "sourceSystem": "my-system",
        "customer": {
            "name": "Docs Test Customer",
            "identifier": "docs-tst-cstmr",
            "costCenter": "333"
        }
    }'
Example Response
HTTP/1.1 201 Created
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Validation Error Fields
Path Type Description

errors

Array

A list of validation errors.

errors[].entity

String

The entity the validation error was identified on.

errors[].property

String

The property the validation error was identified on.

errors[].invalidValue

String

The value that caused the validation error

errors[].message

String

A code for the error that occurred. Can be one of:
not.unique.registration.user.email (The user already exists. Results in Status Code 409)
not.valid.registration.customer.identifier (The customer identifier does not match the regex "^[a-z0-9\-]+$)"
too.long.registration.customer.identifier (The customer identifier is limited to 16 characters)
not.unique.registration.customer.identifier (The customer identifier is already in use by another customer. Results in Status Code 409)

Validation Error Example Response
HTTP/1.1 400 Bad Request
Vary: Origin
Vary: Access-Control-Request-Method
Vary: Access-Control-Request-Headers
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
Strict-Transport-Security: max-age=31536000 ; includeSubDomains
X-Frame-Options: DENY
Content-Length: 191

{
  "errors" : [ {
    "entity" : "registration",
    "property" : "customer.identifier",
    "invalidValue" : "123(abc)",
    "message" : "not.valid.registration.customer.identifier"
  } ]
}