API Overview

Meshes exposes two different API surfaces:

1. the event ingestion API
2. the management API

New users often only need the first one at the start.

1. Event Ingestion API

Use the event ingestion API when your app needs to send product events into Meshes.

Typical use cases:

• browser or mobile clients sending events with a publishable key
• backend services sending events into a workspace
• SDK-based event emission from your product

The main endpoint is:

POST https://events.meshes.io/api/v1/events

Authentication options

• Publishable key via X-Meshes-Publishable-Key Recommended for browser-safe or client-side event ingestion.
• Machine JWT via Authorization: Bearer <token> Recommended for secure server-side environments.

If you are just getting started, this is usually the only API you need after the dashboard quickstart.

Related docs:

• Send Events
• Publishable Keys
• Bulk Event Ingestion

2. Management API

Use the management API when you need to create or manage Meshes resources programmatically.

Typical use cases:

• creating workspaces from your backend
• provisioning connections or rules through your own product flows
• listing event history or delivery results
• managing machine keys and account-level configuration

Management endpoints live under:

https://api.meshes.io/api/v1/...

Important boundary

The management API is server-side only.

Do not call it directly from browser code. Use a secure backend or another trusted server-side layer.

Authentication for the Management API

The management API uses a short-lived machine JWT built from:

• an access key
• a secret key
• an organization context

The token is then sent as:

Authorization: Bearer <jwt_token>

Example: create a machine JWT in Node.js

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!;

const key = new TextEncoder().encode(secretKey);

export async function createMeshesMachineToken() {
  return new SignJWT({
    org: organizationId,
  })
    .setProtectedHeader({
      alg: 'HS256',
      typ: 'JWT',
      kid: accessKey,
    })
    .setIssuer(`urn:meshes:m2m:${accessKey}`)
    .setAudience('meshes-api')
    .setIssuedAt()
    .setExpirationTime('30s')
    .sign(key);
}

Example: use the token in a management API request

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

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

Which One Should You Use?

Use the dashboard + event ingestion API when:

• you are validating the product for the first time
• you want to create connections and rules in the UI
• you just need to emit events from your app

Use the management API when:

• you need to provision or manage Meshes resources from your backend
• you want to automate workspace or rule creation
• you are embedding Meshes into a larger product workflow

Recommended New-User Path

For most teams, the right order is:

1. use the dashboard to create a connection and rule
2. use Send Test Event in the UI to validate delivery
3. emit a real event through the event ingestion API
4. add management API usage later if you need programmatic provisioning

Continue

• Quickstart
• Authentication
• API Documentation
• SDKs