Authentication - MeshAI Documentation

API Keys

MeshAI uses Bearer token authentication. All API keys start with msh_.

curl https://api.meshai.dev/api/v1/agents \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

Key Types

Type	Prefix	Permissions
Admin	`msh_`	Full access: manage agents, policies, billing, users
Proxy	`msh_`	Forward LLM requests through the proxy; read-only agent data
Read-only	`msh_`	Read agents, cost, anomalies; no write operations

Scopes

API keys are scoped to limit permissions:

Scope	Allows
`registry:read`	List and get agents, teams
`registry:write`	Register, update, delete agents and teams
`telemetry:write`	Send heartbeats and usage data
`monitoring:read`	Query monitoring overview
`cost:read`	Query cost endpoints
`anomaly:read`	List and get anomalies
`anomaly:write`	Acknowledge, resolve anomalies
`governance:read`	List policies, approvals, audit events
`governance:write`	Create policies, decide approvals, classify risk
`proxy:forward`	Forward LLM requests through the proxy
`admin`	Full access: manage keys, agents, policies, billing
`platform:admin`	Tenant management (platform admins only)

Scope Restrictions

When creating a new API key, the scopes you can grant depend on your own key’s permissions:

Your scope	Can grant
`platform:admin`	Any scope
`admin`	All scopes except `platform:admin`
Other	Only scopes you already have

Attempting to grant a scope you don’t have returns 403 Forbidden.

Get Current Key Info

GET /auth/me

Returns the scopes and identity of the API key making the request. Useful for determining which scopes are available when creating new keys.

curl https://api.meshai.dev/api/v1/auth/me \
  -H "Authorization: Bearer msh_YOUR_API_KEY"

{
  "success": true,
  "data": {
    "key_id": "01JABC123DEF456",
    "tenant_id": "01JXYZ789GHI012",
    "scopes": ["admin"]
  }
}

Create an API Key

Via Dashboard

Go to app.meshai.dev/settings/api-keys and click “Create API Key”. Select the scopes you need.

Via API

curl -X POST https://api.meshai.dev/api/v1/auth/api-keys \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline-key",
    "scopes": ["registry:read", "registry:write", "telemetry:write"],
    "expires_in_days": 90
  }'

{
  "success": true,
  "data": {
    "id": "01JABC123DEF456",
    "raw_key": "msh_abc123def456...",
    "key_prefix": "msh_abc1",
    "name": "ci-pipeline-key",
    "scopes": ["registry:read", "registry:write", "telemetry:write"],
    "expires_at": "2026-06-15T10:00:00Z",
    "created_at": "2026-03-17T10:00:00Z"
  }
}

The API key is shown once at creation time. Store it securely. You cannot retrieve it later.

Create a new MeshAI account:

curl -X POST https://api.meshai.dev/api/v1/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com",
    "password": "secure-password",
    "company_name": "Acme Corp"
  }'

{
  "success": true,
  "data": {
    "tenant_id": "tnt_abc123",
    "user_id": "usr_def456",
    "api_key": "msh_live_abc123def456",
    "message": "Account created. Check your email to verify."
  }
}

Get a session token for dashboard access or exchange for an API key:

curl -X POST https://api.meshai.dev/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com",
    "password": "secure-password"
  }'

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOi...",
    "token_type": "bearer",
    "expires_in": 3600,
    "tenant_id": "tnt_abc123"
  }
}

Key Rotation

Rotate keys without downtime by creating a new key before deleting the old one:

Create a new key

Create a new API key with the same scopes.

Update your agents

Deploy the new key to all agents and services.

Delete the old key

Once all agents are using the new key, delete the old one:

curl -X DELETE https://api.meshai.dev/api/v1/auth/api-keys/key_old123 \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"

SAML SSO

SAML-based single sign-on for your organization’s identity provider. Available on the Enterprise plan (and Enterprise Plus, and internal partner tenants). All SSO endpoints require the admin scope.

Get SSO Configuration

GET /sso/config

Get the tenant’s current SSO configuration, or null if SSO has not been configured yet.

curl https://api.meshai.dev/api/v1/sso/config \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"

{
  "success": true,
  "data": {
    "id": "01JSSO1CONFIG2ABC3DEF456",
    "provider_name": "Okta",
    "idp_entity_id": "http://www.okta.com/exkabc123",
    "idp_sso_url": "https://acme.okta.com/app/acme_meshai/exkabc123/sso/saml",
    "idp_slo_url": null,
    "enabled": true,
    "auto_provision": true,
    "created_at": "2026-03-01T00:00:00Z"
  }
}

Configure SSO

POST /sso/config

Create or update the tenant’s SAML SSO configuration. Returns 403 if the tenant’s plan does not include SSO.

Field	Type	Required	Description
`provider_name`	string	Yes	Display name for the identity provider (e.g., `Okta`)
`idp_entity_id`	string	Yes	IdP entity ID
`idp_sso_url`	string	Yes	IdP SSO URL
`idp_slo_url`	string	No	IdP single logout URL
`idp_x509_cert`	string	Yes	IdP signing certificate
`auto_provision`	boolean	No	Auto-create users on first SSO login (default `true`)

curl -X POST https://api.meshai.dev/api/v1/sso/config \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_name": "Okta",
    "idp_entity_id": "http://www.okta.com/exkabc123",
    "idp_sso_url": "https://acme.okta.com/app/acme_meshai/exkabc123/sso/saml",
    "idp_x509_cert": "-----BEGIN CERTIFICATE-----..."
  }'

{
  "success": true,
  "data": {
    "id": "01JSSO1CONFIG2ABC3DEF456",
    "created": true
  }
}

Enable SSO

POST /sso/enable

Enable SSO for the tenant. Requires an existing SSO configuration; returns 400 if none exists yet.

curl -X POST https://api.meshai.dev/api/v1/sso/enable \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"

Disable SSO

POST /sso/disable

Disable SSO for the tenant without deleting its configuration.

curl -X POST https://api.meshai.dev/api/v1/sso/disable \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"

Get SP Metadata

GET /sso/metadata

Get the MeshAI service provider metadata your identity provider needs to complete the SAML integration.

curl https://api.meshai.dev/api/v1/sso/metadata \
  -H "Authorization: Bearer msh_YOUR_ADMIN_KEY"

{
  "success": true,
  "data": {
    "entity_id": "https://app.meshai.dev/sso",
    "acs_url": "https://app.meshai.dev/api/auth/sso/callback",
    "name_id_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
  }
}

​API Keys

​Key Types

​Scopes

​Scope Restrictions

​Get Current Key Info

​Create an API Key

​Via Dashboard

​Via API

​Signup

​Login

​Key Rotation

​SAML SSO

​Get SSO Configuration

​Configure SSO

​Enable SSO

​Disable SSO

​Get SP Metadata

API Keys

Key Types

Scopes

Scope Restrictions

Get Current Key Info

Create an API Key

Via Dashboard

Via API

Signup

Login

Key Rotation

SAML SSO

Get SSO Configuration

Configure SSO

Enable SSO

Disable SSO

Get SP Metadata