Getting Started

This guide gets you from an issued service-account key to a verified authenticated request.

1. Choose an Environment

Use staging while building and production only for live traffic.

# Staging
export MESHI_BASE="https://api.staging.meshi.io/api/v0/partner"
export MESHI_KEY="<MESHI_PARTNER_STAGING_KEY>"

# Production
export MESHI_BASE="https://api.meshi.io/api/v0/partner"
export MESHI_KEY="<MESHI_PARTNER_PRODUCTION_KEY>"

Staging and production keys are provisioned separately. A staging key should be used only with the staging base URL, and a production key only with production.

2. Confirm Auth

Call GET /auth before any write. It confirms that your key resolves to an org-scoped service account and shows the scopes available to the key.

curl -sS "$MESHI_BASE/auth" \
  -H "Authorization: Bearer $MESHI_KEY"

Example response:

{
  "org_id": "<ORG_ID>",
  "principal_type": "service_account",
  "service_account_user_id": "<SERVICE_ACCOUNT_USER_ID>",
  "scopes": ["partner:read", "partner:write"],
  "correlation_id": "<CORRELATION_ID>"
}

If scopes does not include partner:write, the key can read but cannot create events, import attendees, trigger enrichment, or trigger matching.

3. Understand Scopes

Scopes are enforced by HTTP method:

Scope	Grants
partner:read	GET, HEAD, and OPTIONS
partner:write	POST, PUT, and all read methods

Read-only methods can be satisfied by either partner:read or partner:write. Write methods require partner:write.

4. Send a Correlation ID

You can send x-correlation-id on any request to thread your own trace ID through the response:

curl -sS "$MESHI_BASE/auth" \
  -H "Authorization: Bearer $MESHI_KEY" \
  -H "x-correlation-id: partner-trace-001"

Meshi echoes the effective ID in the x-correlation-id response header and in every JSON response body. Always log it with integration errors.

5. Make a First Write

Create an event with an ID from your own system:

curl -sS -X POST "$MESHI_BASE/events" \
  -H "Authorization: Bearer $MESHI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "summit-2026",
    "title": "Annual Partner Summit 2026",
    "description": "Two-day leadership summit",
    "start_date": "2026-09-10",
    "end_date": "2026-09-11",
    "timezone": "America/New_York",
    "visibility": "private",
    "url_slug": "summit-2026"
  }'

201 Created returns the event. If the event ID already exists in your org, the response is 409 PARTNER_ID_CONFLICT; treat that as an already-provisioned event and fetch it before continuing.

6. Next Step

Follow the canonical flow to add attendees, poll imports, enrich, match, and read results.