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 API Key client_id and client_secret to make requests to the login endpoint to retrieve an OAuth access token.

Most API endpoints support API Keys with fine-grained permissions that provide separate permissions for read, create or update and delete permissions. Please review the permissions in meshPanel for a full list of supported 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.

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 "https://<your meshStack API host>/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.