API Overview

Meshes exposes a REST API for managing workspaces, events, rules, and connections.

Most server-side integrations use:

• Machine Keys – per-user access keys (access + secret) used as personal access tokens for server-side API calls. Each key can be scoped to specific organizations, workspaces, and permissions.
• Organization ID – identifies which organization/account the request should operate on. Many endpoints are also scoped to a workspace within that organization.

Authentication

Use your Machine Key to build a short-lived JWT that will be sent in the Authorization header:

Authorization: Bearer <jwt_token>

Machine Tokens should only be created and used from secure server-side environments (never in client-side or browser code).

Example: Creating a Machine JWT in Node.js (jose)

See the API docs for full details on the JWT claims and validation rules.

import { SignJWT } from 'jose';

const accessKey = process.env.MESHES_ACCESS_KEY!;
const secretKey = process.env.MESHES_SECRET_KEY!;
const organizationId = process.env.MESHES_ORG_ID!;

// jose requires a Uint8Array for symmetric HS256 keys
const key = new TextEncoder().encode(secretKey);

export async function createMeshesMachineToken() {
  const token = await new SignJWT({
    org: organizationId,
  })
    .setProtectedHeader({
      alg: 'HS256',
      typ: 'JWT',
      kid: accessKey,
    })
    .setIssuer(`urn:meshes:m2m:${accessKey}`)
    .setAudience('meshes-api')
    .setIssuedAt() // automatically sets iat (seconds)
    .setExpirationTime('30s') // must be <= 60s
    .sign(key);

  return token;
}

Example: Using the token in an API call

TOKEN="$(node ./scripts/create-meshes-token.mjs)"

curl https://api.meshes.io/api/v1/workspaces \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json"

For the full, interactive OpenAPI reference (schemas, endpoints, and example requests), see:

Meshes API Documentation