Developer overview

Base URLs

Older per-tool hosts of the form <tool>-api.easerix.com are retired — use the bases above. Endpoints are versioned under /v1/, so a full URL looks like https://api.easerix.com/links/v1/links.

Authentication

Easerix has two ways in: API keys for scripts, integrations, and CI, and OAuth 2.1 for apps that act on behalf of a user (this is what the MCP server and the CLI use).

API keys

Create keys at account.easerix.com:

• Personal keys (esrx_u_...) — under API keys. The key acts as you, in one workspace you pick when creating it.
• Workspace keys (esrx_o_...) — under your organization's API keys page (requires settings permission, team workspaces only). These are service accounts: they act as a role you choose — member, billing, or admin, never owner.

Either kind can be restricted to specific tools and given an expiry (1 year by default, 90 days, or never). The full key is shown once at creation — store it in a secret manager. Revoke any key from the same page.

Using a key: exchange it for an access token

API keys are never sent to the tool APIs directly. Exchange the key for a short-lived access token first:

curl -s https://auth.easerix.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "esrx_u_..."}'

{
  "access_token": "<JWT>",
  "expires_at": "2026-08-09T18:04:05Z",
  "org": { "id": "...", "name": "...", "role": "member", "tools": ["links", "tasks"] }
}

There is no refresh token — when expires_at passes, exchange the key again. Then call any tool API with the token:

curl -s https://api.easerix.com/links/v1/links \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Sending the raw esrx_... key as a Bearer token to a tool API returns 401.

OAuth 2.1

auth.easerix.com is a standards-compliant OAuth 2.1 authorization server:

Registered clients are public (no client secret) and must use PKCE with S256. When a user approves your app they grant it one workspace; the tokens you receive are scoped to that workspace and to the tools enabled there. Users can revoke a grant anytime under account.easerix.com → Connected apps.

MCP-compliant AI clients drive this whole flow automatically — see MCP server.

Errors

Every non-2xx response has the same body — one human-readable field:

{ "error": "missing bearer token" }

Status codes follow convention: 400 for invalid input, 401 for missing or expired credentials, 403 for a role or permission you don't have, 404 for anything that doesn't exist. Note that resources outside your workspace also read as 404, never 403 — the API doesn't confirm the existence of things you can't access.

Workspace scoping

Every resource belongs to the workspace your token was issued for. A token carries the workspace, your role in it, and the tools enabled there; a request to a tool that isn't enabled for the workspace is rejected. To work across two workspaces, create a key (or grant) per workspace.

Next steps

• Browse the API reference — every endpoint, generated from the OpenAPI specs
• Connect an AI client over MCP
• Receive webhooks

Frequently asked questions

How long do access tokens last?

They're short-lived. Don't hardcode a duration — read expires_at from the exchange response and re-exchange your API key when it passes.

Can I use one API key across all my workspaces?

No. A key is bound to a single workspace at creation. Create one key per workspace you need to automate.

Where do I find the OpenAPI specs?

Each API's raw spec is linked from the API reference — for example links.v1.yaml. They're standard OpenAPI 3 YAML, ready for client generators.