Skip to main content

OAuth API Keys

API keys authorize requests towards the meshObject API within the scope of the workspace owning the API key. To issue workspace-scoped API Keys, navigate to the admin or workspace area. Follow these steps:

  1. Open the respective workspace.
  2. Go to Workspace Access > API Keys.
  3. Issue a new API key by clicking + Create API Key.
  4. Provide a name and select permissions the API key shall get.
  5. Use the Key ID and the Key Secret of the API key to get an access token from the login endpoint, see below.

Most API endpoints support API Keys with fine-grained permissions that provide separate permissions for read, create or update and delete permissions. API Permissions lists all permissions.

You can also assign "Admin permissions" to an API key. While normal permissions scope access to resources owned by the workspace the API key is issued for, "Admin permissions" allow access to all resources in meshStack. Admin permissions can only be assigned to an API Key from the admin area in meshPanel.

You can only add permissions to an API key that you hold yourself. A few permissions exist for automation only and no role holds them, for example the permissions for Terraform state. You can add these anyway. When you edit an API key, you can keep or remove every permission that is already on it. An API key that manages other API keys can only pass on permissions that it holds itself.

Get a Token for Your API Key​

Send the Key ID and the Key Secret of your API key to the login endpoint. We recommend the JSON variant, because it returns the token directly:

curl -X POST "<your meshStack API URL>/api/login" \
  -H "Content-Type: application/json" \
  -d '{"clientId": "<Key ID>", "clientSecret": "<Key Secret>"}'

The response contains the token in access_token and its lifetime in seconds in expires_in. Set it as the Authorization header of your requests:

Authorization: Bearer <access_token>

The token is short-lived. Request a new one when it expires.

Use Your API Key With the meshStack CLI and Terraform​

You can store an API key in a profile of the meshStack CLI. The CLI then gets and renews the token for you:

meshstack login --endpoint <your meshStack API URL> --profile <profile name> --apikey=<Key ID> --stdin

The CLI asks for the Key Secret. Paste it and press Enter. The CLI shows what you type, so make sure that nobody can see your screen.

The meshStack Terraform provider can use the same profile:

provider "meshstack" {
  profile = "<profile name>"
}

In a CI/CD pipeline, set apikey in the provider block and pass the Key Secret in the MESHSTACK_API_SECRET environment variable instead.

Give an API Key to an AI Agent​

An AI agent that works next to you should use your own CLI login instead of an API key, so that it acts with your permissions and shows up as you. Give an API key only to an agent that runs without you, and add only the permissions its task needs. See How to Work With AI Agents.