meshcloud Public API Docs

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. We also provide a Postman collection and openAPI documentation.

Postman Collection

OpenAPI documentation

The first step for being able to use the new Postman Collection is to import it in Postman. To proceed, configure the credentials in the "Authorization" tab of this collection. These credentials can be retrieved from the panel by creating a new API User or by using the credentials of an already existing API User. Finally, set the hostname variable to ensure that the requests are ready to be executed.

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. API users, which can be used for basic auth, can be created via meshPanel. These API users are only available for users with Partner Admin rights.

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

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

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

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.
`422 Unprocessable Entity`	The request contained one or more entities with an error like a non existing referenced entity.
`500 Internal Server Error`	An internal error occurred while processing the request. Most likely these are temporary communication errors with external services.

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.

422 Unprocessable Entity

The request contained one or more entities with an error like a non existing referenced entity.

500 Internal Server Error

An internal error occurred while processing the request. Most likely these are temporary communication errors with external services.

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.

Notice that HAL hrefs can be templated: For example, if an endpoint requires a path variable, the _links array may include an entry like the following:

{
  "_links" : {
    "users" : {
      "href" : "https://example-url.org/api/users/{username}",
      "templated" : true
    }
  }
}

Please refer to the HAL specification for more details about template URIs.

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

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 350. Greater values will be automatically lowered to this value.

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 350. 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.

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.

Links

List of all top-level endpoints the authenticated user has access to. Depending on your rights, you will only get a subset of the links mentioned here.

Relation Description

Relation	Description
`metadata`	The Metadata API to retrieve metadata from meshStack.
`meshobjects`	The MeshObjects API to get, create, update and delete meshObjects.

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" : {
    "metadata" : {
      "href" : "https://mesh-backend-url/api/metadata"
    },
    "meshobjects" : {
      "href" : "https://mesh-backend-url/api/meshobjects"
    },
    "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.meshobjects.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.

Links

List of all meshObject endpoints the authenticated user has access to. Depending on your rights, you will only get a subset of the links mentioned here.

Relation Description

Relation	Description
`meshcustomers`	Get meshCustomers.
`meshcustomerusergroups`	Get meshCustomerUserGroups.
`meshprojects`	Get meshProjects.
`meshtenants`	Get meshTenants.
`meshpaymentmethods`	Get meshPaymentMethods.
`meshusers`	Get meshUsers.

meshcustomers

Get meshCustomers.

meshcustomerusergroups

Get meshCustomerUserGroups.

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: 966

{
  "_links" : {
    "meshcustomers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers"
    },
    "meshcustomerusergroups" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomerusergroups"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers/{username}",
      "templated" : true
    },
    "meshprojects" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects{?customerIdentifier,paymentIdentifier}",
      "templated" : true
    },
    "meshpaymentmethods" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods{?customerIdentifier}",
      "templated" : true
    },
    "meshtenants" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants{?customerIdentifier,projectIdentifier,platformIdentifier}",
      "templated" : true
    },
    "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: 3993

{
  "_embedded" : {
    "meshCustomers" : [ {
      "apiVersion" : "v1",
      "kind" : "meshCustomer",
      "metadata" : {
        "name" : "admin-customer",
        "createdOn" : "2023-06-07T16:07:10Z"
      },
      "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"
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=admin-customer"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
        },
        "meshpaymentmethods" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=admin-customer"
        },
        "meshcustomerusergroups" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomerusergroups?customerIdentifier=admin-customer"
        }
      }
    }, {
      "apiVersion" : "v1",
      "kind" : "meshCustomer",
      "metadata" : {
        "name" : "demo-customer",
        "createdOn" : "2023-06-07T16:07:10Z"
      },
      "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"
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=demo-customer"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
        },
        "meshpaymentmethods" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=demo-customer"
        },
        "meshcustomerusergroups" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomerusergroups?customerIdentifier=demo-customer"
        }
      }
    }, {
      "apiVersion" : "v1",
      "kind" : "meshCustomer",
      "metadata" : {
        "name" : "demo-partner",
        "createdOn" : "2023-06-07T16:07:10Z"
      },
      "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"
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=demo-partner"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
        },
        "meshpaymentmethods" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=demo-partner"
        },
        "meshcustomerusergroups" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomerusergroups?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" : 5,
    "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.

Customer Links
Relation	Description
`meshprojects`	Link to fetch all meshProjects of this customer.
`meshtenants`	Link to fetch all meshTenants of this customer.
`meshusers`	Link to fetch all meshUsers of this customer.
`meshpaymentmethods`	Link to fetch all meshPaymentMethods of this customer.
`meshcustomerusergroups`	Link to fetch all meshCustomerUserGroups of this customer.

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: 1012

{
  "apiVersion" : "v1",
  "kind" : "meshCustomer",
  "metadata" : {
    "name" : "admin-customer",
    "createdOn" : "2023-06-07T16:07:10Z"
  },
  "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"
    },
    "meshprojects" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=admin-customer"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
    },
    "meshpaymentmethods" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=admin-customer"
    },
    "meshcustomerusergroups" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomerusergroups?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)
`paymentIdentifier`	Filter for meshProjects that have the meshPaymentMethod with given identifier assigned. Substitute Payment Methods on meshProjects are not considered! Use an empty or blank value to filter for meshProjects without an assigned meshPaymentMethod. (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=sm7m5mpds1&paymentIdentifier=test-payment&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=sm7m5mpds1&paymentIdentifier=test-payment&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: 1782

{
  "_embedded" : {
    "meshProjects" : [ {
      "apiVersion" : "v1",
      "kind" : "meshProject",
      "metadata" : {
        "name" : "test-project-1",
        "ownedByCustomer" : "sm7m5mpds1",
        "createdOn" : "2023-06-07T16:08:02.080613Z"
      },
      "spec" : {
        "displayName" : "Test Project 1",
        "tags" : { },
        "paymentMethodIdentifier" : "test-payment"
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects/sm7m5mpds1.test-project-1"
        },
        "meshtenants" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=sm7m5mpds1&projectIdentifier=test-project-1"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
        },
        "activePaymentMethod" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=sm7m5mpds1&paymentIdentifier=test-payment&page=0&size=1"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=sm7m5mpds1&paymentIdentifier=test-payment&page=0&size=1"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=sm7m5mpds1&paymentIdentifier=test-payment&page=1&size=1"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?customerIdentifier=sm7m5mpds1&paymentIdentifier=test-payment&page=1&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 2,
    "totalPages" : 2,
    "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/sm7m5mpds1.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/sm7m5mpds1.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 been submitted for deletion by a Customer Admin, the date, the date is represented here (e.g. `2020-12-22T09:37:43Z)`. Otherwise this field is missing.
`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.

Project Links
Relation	Description
`meshtenants`	Link to fetch all meshTenants of this project.
`meshusers`	Link to fetch all meshUsers having access to this project.
`activePaymentMethod`	Link to fetch the active meshPaymentMethod of this project.
`substitutePaymentMethod`	Link to fetch the substitute meshPaymentMethod of this project.

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: 833

{
  "apiVersion" : "v1",
  "kind" : "meshProject",
  "metadata" : {
    "name" : "test-project-1",
    "ownedByCustomer" : "sm7m5mpds1",
    "createdOn" : "2023-06-07T16:08:02.080613Z"
  },
  "spec" : {
    "displayName" : "Test Project 1",
    "tags" : { },
    "paymentMethodIdentifier" : "test-payment"
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects/sm7m5mpds1.test-project-1"
    },
    "meshtenants" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=sm7m5mpds1&projectIdentifier=test-project-1"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers"
    },
    "activePaymentMethod" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment"
    }
  }
}

meshTenant

All endpoints on meshTenants.

List meshTenants

Provides a paged list of meshTenants. By default, list all active meshTenants (neither deleted nor submitted for deletion).

Note: If the deletion state is not specified, only active meshTenants are returned.

Request Headers
Name	Description
`Accept`	meshApi is versioned and you should use `application/vnd.meshcloud.api.meshtenant.v2.hal+json` as an `Accept` header to be guaranteed the V2 response format of this endpoint. New versions might 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)
`deletionState`	Filter for meshTenants with a certain deletion state. Possible values are: [ACTIVE](default option) All meshTenants that are not deleted or submitted for deletion,[MARKED_FOR_DELETION] All meshTenants that are awaiting manual deletion approval, or [DELETED] All meshTenants that are deleted or submitted for deletion
`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&deletionState=MARKED_FOR_DELETION&page=0&size=1 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshtenant.v2.hal+json
Host: mesh-backend-url

Example Curl Request

$ curl 'https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=test-customer&projectIdentifier=test-project&deletionState=MARKED_FOR_DELETION&page=0&size=1' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshtenant.v2.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.v2.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: 1896

{
  "_embedded" : {
    "meshTenants" : [ {
      "apiVersion" : "v2",
      "kind" : "meshTenant",
      "metadata" : {
        "ownedByProject" : "test-project",
        "ownedByCustomer" : "test-customer",
        "platformIdentifier" : "azure.meshcloud-azure-dev",
        "deletedOn" : "2023-06-08T16:08:03.660889Z",
        "assignedTags" : { }
      },
      "spec" : {
        "localId" : "0ed0c2c4-426e-4e33-a069-b23880054858",
        "landingZoneIdentifier" : "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"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=test-customer&projectIdentifier=test-project&deletionState=MARKED_FOR_DELETION&page=0&size=1"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=test-customer&projectIdentifier=test-project&deletionState=MARKED_FOR_DELETION&page=0&size=1"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=test-customer&projectIdentifier=test-project&deletionState=MARKED_FOR_DELETION&page=1&size=1"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshtenants?customerIdentifier=test-customer&projectIdentifier=test-project&deletionState=MARKED_FOR_DELETION&page=1&size=1"
    }
  },
  "page" : {
    "size" : 1,
    "totalElements" : 2,
    "totalPages" : 2,
    "number" : 0
  }
}

Get meshTenant

Get a single meshTenant. A meshTenant submitted for deletion by a Customer Admin can also be requested via this endpoint.

Request Headers
Name	Description
`Accept`	meshApi is versioned and you should use `application/vnd.meshcloud.api.meshtenant.v2.hal+json` as an `Accept` header to be guaranteed the V2 response format of this endpoint. New versions might 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.v2.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.v2.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.deletedOn`	`String`	If the meshTenant has been submitted for deletion by a Customer Admin, the date, the date is represented here (e.g. `2020-12-22T09:37:43Z)`. Otherwise this field is missing.
`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.landingZoneIdentifier`	`String`	The identifier of the Landing Zone of this meshTenant. This field will be empty if the meshTenant has no Landing Zone.
`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.v2.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: 796

{
  "apiVersion" : "v2",
  "kind" : "meshTenant",
  "metadata" : {
    "ownedByProject" : "test-project",
    "ownedByCustomer" : "test-customer",
    "platformIdentifier" : "azure.meshcloud-azure-dev",
    "deletedOn" : "2023-06-08T16:08:03.660889Z",
    "assignedTags" : { }
  },
  "spec" : {
    "localId" : "0ed0c2c4-426e-4e33-a069-b23880054858",
    "landingZoneIdentifier" : "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"
    }
  }
}

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=sm7m5mpmds1&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=sm7m5mpmds1&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: 1937

{
  "_embedded" : {
    "meshPaymentMethods" : [ {
      "apiVersion" : "v1",
      "kind" : "meshPaymentMethod",
      "metadata" : {
        "name" : "test-payment-method-1",
        "ownedByCustomer" : "sm7m5mpmds1"
      },
      "spec" : {
        "displayName" : "Test Payment Method 1",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment-method-1"
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?paymentIdentifier=test-payment-method-1"
        }
      }
    }, {
      "apiVersion" : "v1",
      "kind" : "meshPaymentMethod",
      "metadata" : {
        "name" : "test-payment-method-2",
        "ownedByCustomer" : "sm7m5mpmds1"
      },
      "spec" : {
        "displayName" : "Test Payment Method 2",
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment-method-2"
        },
        "meshprojects" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?paymentIdentifier=test-payment-method-2"
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=sm7m5mpmds1&page=0&size=2"
    },
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=sm7m5mpmds1&page=0&size=2"
    },
    "next" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=sm7m5mpmds1&page=1&size=2"
    },
    "last" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods?customerIdentifier=sm7m5mpmds1&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.

PaymentMethod Links
Relation	Description
`meshprojects`	Get meshProjects, that are assigned to this payment method. Substitute Payment Methods on meshProjects are not considered!

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: 516

{
  "apiVersion" : "v1",
  "kind" : "meshPaymentMethod",
  "metadata" : {
    "name" : "test-payment-method-1",
    "ownedByCustomer" : "sm7m5mpmds1"
  },
  "spec" : {
    "displayName" : "Test Payment Method 1",
    "tags" : { }
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshpaymentmethods/test-payment-method-1"
    },
    "meshprojects" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshprojects?paymentIdentifier=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: In order to filter on CustomerUserGroups you must only specify the customerUserGroup Identifier and none of the other request parameters.

In case you filter on roles the response contains all meshUsers with that role regardless if they have been assigned directly or via a group. This offers for example a great opportunity to find the (contact) information of all Customer Admins within one request, whereas the upcoming endpoints for the bindings (i.e. meshCustomerUserBinding, meshCustomerGroupBinding etc.) are not sufficient for this use-case. For that purpose several requests are required to cover direct user bindings and bindings via groups.

Note: 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)
`firstName`	Filter for meshUsers based on their first name. (optional)
`lastName`	Filter for meshUsers based on their last name. (optional)
`username`	Filter for meshUsers based on their username. (optional)
`email`	Filter for meshUsers based on their E-mail. (optional)
`euid`	Filter for meshUsers based on their EUID. (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: 1539

{
  "_embedded" : {
    "meshUsers" : [ {
      "apiVersion" : "v1",
      "kind" : "meshUser",
      "metadata" : {
        "name" : "john-doe"
      },
      "spec" : {
        "email" : "john-doe@example.com",
        "firstName" : "John",
        "lastName" : "Doe",
        "euid" : "c104b650-5e65-4da6-9edd-fa1ea9e09f7f",
        "tags" : {
          "environment" : [ "dev", "test", "qa" ]
        }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers/john-doe"
        },
        "meshcustomerusergroups" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomerusergroups?username=john-doe"
        }
      }
    } ]
  },
  "_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
  }
}

Get meshUser

Get a single meshUser. Deleted meshUsers are not provided via this endpoint.

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.

Example Request

GET /api/meshobjects/meshusers/john-doe 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/john-doe' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshuser.v1.hal+json'

Response Fields
Path	Type	Description
`apiVersion`	`String`	Version of meshUser 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 'meshUser' for this endpoint.
`metadata`	`Object`	Always contains the 'name' to uniquely identify the meshUser.
`metadata.name`	`String`	The userIdentifier as 'name' to uniquely identify the meshUser.
`spec`	`Object`	All fields in this section describe the meshUser.
`spec.email`	`String`	The email of the meshUser.
`spec.firstName`	`String`	The firstname of the meshUser.
`spec.lastName`	`String`	The lastname of the meshUser.
`spec.euid`	`String`	External User ID which is used to lookup the user in the cloud platforms.
`spec.tags`	`Object`	Key/Value pairs of tags set on the meshUser. Keep in mind, that values are an array. Also see our general section about Tags
`_links`	`Object`	Available links [links] on a meshUser.

User Links
Relation	Description
`meshcustomerusergroups`	Link to fetch all meshcustomerusergroups of this user.

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: 577

{
  "apiVersion" : "v1",
  "kind" : "meshUser",
  "metadata" : {
    "name" : "john-doe"
  },
  "spec" : {
    "email" : "john-doe@example.com",
    "firstName" : "John",
    "lastName" : "Doe",
    "euid" : "c104b650-5e65-4da6-9edd-fa1ea9e09f7f",
    "tags" : {
      "environment" : [ "dev", "test", "qa" ]
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers/john-doe"
    },
    "meshcustomerusergroups" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomerusergroups?username=john-doe"
    }
  }
}

meshCustomerUserGroup

All endpoints on meshCustomerUserGroups.

List meshCustomerUserGroups

Provides a paged list of meshCustomerUserGroups.

Request Headers
Name	Description
`Accept`	meshApi is versioned and you should use `application/vnd.meshcloud.api.meshcustomerusergroup.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.
`customerIdentifier`	Filter for meshCustomerUserGroups that belong to the meshCustomer with given identifier. (optional)
`username`	Filter for meshCustomerUserGroups that belong to the meshUser with given username. (optional)

Example Request

GET /api/meshobjects/meshcustomerusergroups?username=sample-user&page=0&size=3 HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshcustomerusergroup.v1.hal+json
Host: mesh-backend-url

Example Curl Request

$ curl 'https://mesh-backend-url/api/meshobjects/meshcustomerusergroups?username=sample-user&page=0&size=3' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshcustomerusergroup.v1.hal+json'

Response Fields
Path	Type	Description
`_embedded`	`Object`	Contains the actual content of the paged response.
`_embedded.meshCustomerUserGroups[]`	`Array`	List of meshCustomerUserGroup.
`_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.meshcustomerusergroup.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: 1077

{
  "_embedded" : {
    "meshCustomerUserGroups" : [ {
      "apiVersion" : "v1",
      "kind" : "meshCustomerUserGroup",
      "metadata" : {
        "name" : "my-user-group",
        "ownedByCustomer" : "sample-customer"
      },
      "spec" : {
        "displayName" : "My User Group",
        "members" : [ "sample-user" ],
        "tags" : { }
      },
      "_links" : {
        "self" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomerusergroups/sample-customer.my-user-group"
        },
        "meshcustomer" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers/sample-customer"
        },
        "meshusers" : {
          "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerUserGroupIdentifier=my-user-group"
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomerusergroups?username=sample-user&page=0&size=3"
    }
  },
  "page" : {
    "size" : 3,
    "totalElements" : 1,
    "totalPages" : 1,
    "number" : 0
  }
}

Get meshCustomerUserGroup

Get a single meshCustomerUserGroup by a composed identifier containing customer-identifier and group-identifier connected with a dot (e.g. "customer-identifier.group-identifier"). For global groups, the customer identifier is always "meshcloud-global-partner".

Request Headers
Name	Description
`Accept`	meshApi is versioned and you should use `application/vnd.meshcloud.api.meshcustomerusergroup.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/meshcustomerusergroups/sample-customer.my-user-group HTTP/1.1
Authorization: Basic dmFsaWRfdXNlcm5hbWU6dmFsaWRfcGFzc3dvcmQ=
Accept: application/vnd.meshcloud.api.meshcustomerusergroup.v1.hal+json
Host: mesh-backend-url

Example Curl Request

$ curl 'https://mesh-backend-url/api/meshobjects/meshcustomerusergroups/sample-customer.my-user-group' -i -u 'valid_username:valid_password' -X GET \
    -H 'Accept: application/vnd.meshcloud.api.meshcustomerusergroup.v1.hal+json'

Response Fields
Path	Type	Description
`apiVersion`	`String`	Version of meshCustomerUserGroup 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 'meshCustomerUserGroup' for this endpoint.
`metadata`	`Object`	Always contains the 'name' to uniquely identify the meshCustomerUserGroup. It also contains the customer name that owns this CustomerUserGroup.
`metadata.name`	`String`	The customerUserGroupIdentifier as 'name' to uniquely identify the meshCustomerUserGroup.
`metadata.ownedByCustomer`	`String`	The identifier of the customer that owns this CustomerUserGroup.
`spec`	`Object`	All fields in this section describe the meshCustomerUserGroup.
`spec.displayName`	`String`	The display name of the meshCustomerUserGroup as it is shown in meshPanel.
`spec.egid`	`String`	External Group Identifier, this is an optional field.
`spec.members`	`Array`	List of usernames
`spec.tags`	`Object`	Key/Value pairs of tags set on the meshCustomerUserGroup. Keep in mind, that values are an array. Also see our general section about Tags
`_links`	`Object`	Available links [links] on a meshCustomerUserGroup.

CustomerUserGroup Links
Relation	Description
`meshcustomer`	Link to fetch meshCustomer that owns this CustomerUserGroup.
`meshusers`	Link to fetch all meshUsers being part of this CustomerUserGroup.

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.meshcustomerusergroup.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: 669

{
  "apiVersion" : "v1",
  "kind" : "meshCustomerUserGroup",
  "metadata" : {
    "name" : "my-user-group",
    "ownedByCustomer" : "sample-customer"
  },
  "spec" : {
    "displayName" : "My User Group",
    "members" : [ "sample-user" ],
    "tags" : { }
  },
  "_links" : {
    "self" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomerusergroups/sample-customer.my-user-group"
    },
    "meshcustomer" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshcustomers/sample-customer"
    },
    "meshusers" : {
      "href" : "https://mesh-backend-url/api/meshobjects/meshusers?customerUserGroupIdentifier=my-user-group"
    }
  }
}

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 Parameters
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 , SERVER_ERROR (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 of a meshCustomer/-Partner	yes	yes
meshCustomerUserBinding	assigns users to meshCustomer/-Partner	yes	yes
meshCustomerGroupBinding	assigns groups to meshCustomer/-Partner	yes	yes
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.

We strongly recommend assigning a single Customer Owner when importing a meshCustomer. You can assign a Customer Owner via the meshCustomerUserBinding. Having a Customer Owner is a best practice advocated by meshcloud. It allows you to have a clear responsibility and ownership of the meshCustomer. This is useful when you want to get in touch with someone from a particular meshCustomer and you need a clear contact person.

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 # The name of the meshCustomer can be any length and contain any characters.
  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-31",
    "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

A meshCustomerUserGroup is a user group which can be owned by a meshCustomer/meshPartner.

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

A meshCustomerUserBinding is an assignment of users to a meshCustomer/meshPartner.

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/meshPartner with the specified role. All users in the group will receive the rights from the role. The Customer Owner role cannot be assigned to groups. It is only possible to assign users directly to that 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: v2
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.
  landingZoneIdentifier: test-landing-zone-id # (optional) The identifier of the landing zone.
  quotas: # Only for platforms that support quotas
    - key: limits.cpu
      value: 2000
    - key: limits.memory
      value: 100000

{
  "apiVersion": "v2",
  "kind": "meshTenant",
  "metadata": {
    "ownedByProject": "mobile-app-prod",
    "ownedByCustomer": "my-mobile-app-team",
    "platformIdentifier": "platform-identifier.location-identifier"
  },
  "spec": {
    "localId": "test-tenant",
    "landingZoneIdentifier": "test-landing-zone-id",
    "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" : "D1s8iGmMYn"
}

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.

Links

List of all metadata endpoints the authenticated user has access to. Dependent on your rights, you will only get a subset of the links mentioned here.

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" ]
  }
}