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​

You can explore available endpoints in this documentation and use the integrated Request tool to test them against your meshStack. Alternatively you can download the OpenAPI specification or Postman Collection to use locally in your favorite tools.

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.
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 apiUrl to the API host of your meshStack, for example 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 endpoint individually using custom media types. You must provide a versioned Accept and Content-Type header in every request. See Versioning for more details.

Using the Postman Collection​

You can use the provided Postman Collection to quickly get started with the API:

  1. Import the Postman Collection into Postman.
  2. Open the Authorization tab of the collection and configure your API Key credentials.
  3. Set the hostname collection variable to your meshStack instance URL.