Skip to main content

Introduction

The meshStack API allows you to read and manage resources in meshStack programmatically. This page helps you get started.

tip

If you are not familiar with the different types of objects in meshStack, we recommend reading about them in the product documentation before working with the API.

Getting Started​

Download the OpenAPI Specification​

The OpenAPI specifications describe every endpoint, with its versions, parameters and examples. Use them to generate clients or to import the API into your tools:

You can also try the endpoints on the pages of this documentation. For Postman, there are ready-made collections, see Using the Postman Collection.

Authentication​

The meshStack API takes a bearer token in the Authorization header. How you get the token depends on who calls the API:

Who Calls the APIHow to Authenticate
You, as a personLog in with the meshStack CLI: run meshstack login. The CLI calls the API with your own permissions. We recommend this for everyone who works with the API by hand. See meshStack CLI Login.
Automation, for example a CI/CD pipelineUse an API key. Your automation exchanges the key for a token at POST /api/login. API Permissions lists the permission each endpoint needs.
A building block runUse the token in MESHSTACK_API_TOKEN that meshStack gives the run when its definition uses ephemeral API keys.
Existing integrations with an API userUse Basic authentication with an API user. API users are deprecated. Only the declarative import, the meshObjectCollection endpoints and the metering API still need them.

Each endpoint in this documentation shows what it takes: a bearer token, or Basic authentication with an API user.

Try It in This Documentation​

You can send requests from this documentation with your own login:

  1. Run meshstack login and log in to your meshStack.
  2. Run meshstack auth token and copy the token it prints. It is for the default workspace that meshstack login stored; add --workspace <workspace identifier> for another one.
  3. On an endpoint page, set endpoint to the URL of your meshStack API, for example https://example.meshstack.io.
  4. Paste the token into the Bearer Token field and send the request.

The token is short-lived. When requests start to fail with 401 Unauthorized, run meshstack auth token again.

For scripts, use meshstack api instead of copying tokens around. It sends the request with your login and renews the token for you.

Versioning​

The meshStack API versions each meshObject kind on its own through media types. Always send the versioned media type in the Accept header; without it, meshStack answers 406 Not Acceptable. When you send a body, also set it in the Content-Type header. See Versioning.

Using the Postman Collection​

  1. Import the collection for the meshStack API or the metering API into Postman.
  2. Set the collection variable endpoint to the URL of your meshStack API, for example https://example.meshstack.io.
  3. Set clientId and clientSecret to the Key ID and Key Secret of your API key.
  4. Send API Key Login. It stores the token in bearerToken, and all other requests use it.

The metering collection uses Basic authentication: set basicAuthUsername and basicAuthPassword instead.

Learn More​

  • Technical Specifications: status codes, errors, paging and sorting, hypermedia links, versioning and the deprecation policy.
  • Deprecated Resources: outdated and deprecated versions with their end-of-life dates.
  • API Permissions: which permission an API key needs for each endpoint.
  • All meshObjects: the meshObjects that the declarative import takes, with YAML and JSON examples.