Front API Explained (Auth, Rate Limits & Core Endpoints)

The base URL and the two ways to authenticate

Every request goes to the same host. Front's Core API always works against https://api2.frontapp.com as the base URL, and it speaks JSON over HTTPS. Per Front's authentication docs, there are two ways to prove who you are.

API tokens are the simplest. You generate a token in Front under Settings → Developers → API tokens (Company settings), and you send it on every request in the Authorization header, prefixed with the word Bearer. Front recommends API tokens for testing and for single-customer integrations — anything where you control both ends and just need to talk to one Front company.

OAuth is the other route, and it's the one Front recommends (and often requires) for public integrations or anything built on its application framework — an app that other companies install and that acts on their behalf. OAuth trades a longer setup for the ability to serve many customers without each of them minting a raw token.

For most internal automations — the kind a support or ops team wires up against their own Front — an API token is exactly right. Here's the anatomy of the simplest possible authenticated call:

curl --request GET \
  --url https://api2.frontapp.com/me \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'

A 200 comes back with the company the token belongs to. That single call — GET /me — is the standard "am I authenticated?" smoke test before you build anything heavier.

How tokens are scoped

A Front API token isn't a single all-powerful key — it's shaped along three axes, and understanding them saves you a lot of confusing 403s. Front's token model breaks down into features, namespaces, and granular permissions.

Features decide what kind of work the token can do: Access resources for ordinary Core API reads and writes, Auto-provisioning for SCIM user management, Application triggers for event-driven apps, and an MCP server feature for connecting Front to LLM clients. Namespaces decide which slice of data the token can touch: Global resources (company-level), Shared resources (a specific workspace), or Private resources (a single teammate's data). And within all that, four granular permissions control the verbs, as Front documents them:

1. Read — retrieving resource information.
2. Write — creating and updating resources.
3. Delete — removing API resources.
4. Send — creating and sending messages (starting or replying to conversations), which Front deliberately separates from historical message import.

The practical takeaway: scope tokens tightly. A token that only needs to read conversations should carry Read on the right namespace and nothing else. This is exactly why our own demo token, scoped to global company resources, returns a clean 200 on GET /me but a 403 on GET /conversations — the token simply wasn't granted that reach, which is the security model working as intended rather than a bug.

Rate limits, and how they're counted

This is the part that surprises people, so it's worth getting exact. Per Front's rate limit documentation, the default per-minute allowance depends on your plan, and it is enforced per company, not per token — spinning up more tokens does not buy you more throughput.

On top of the per-minute ceiling there are per-second, per-resource limits. Analytics exports and reports (Tier 1) are throttled to 1 request/sec. High-traffic resources like conversations, messages, and channels (Tier 2) allow 5 requests per resource per second. And the "mark as seen" endpoint is capped at 10 requests per message per hour.

Front also gives you a burst allowance equal to half your plan's per-minute limit for temporary spikes — but once you exhaust it, it takes 10 minutes to replenish. When you do go over, Front returns 429 Too Many Requests with a retry-after header telling you how many seconds to wait. You never have to guess how close you are: every response carries x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset, and x-ratelimit-burst-remaining headers. Read them, back off on 429, and honour retry-after — that's the whole discipline.

The core endpoints

Front's Core API is a backend API that gives control over essentially every entity in Front. A handful of resource families cover the overwhelming majority of real integrations, per Front's Core API overview:

• Conversations — the central object. Read, create, update, and delete threads across email, SMS, chat, and social, plus actions like assign, archive, restore, snooze, follow, and merge.
• Messages — send and reply on new or existing conversations across any channel. There's also an inbound import path for syncing history without actually sending anything to a customer.
• Contacts — create and update the people (and their handles) your conversations are with; the natural sync point between Front and your CRM.
• Drafts — create, edit, and delete draft replies assigned to a teammate or a shared inbox. This is the endpoint an assistive tool uses to suggest a reply a human then approves — rather than sending on its own.
• Channels, teammates, tags, comments, and analytics round out the surface for routing, internal notes, and reporting.

A typical read looks like this:

curl --request GET \
  --url 'https://api2.frontapp.com/conversations?limit=25' \
  --header 'Authorization: Bearer YOUR_API_TOKEN'

Responses are JSON, cursor-paginated (follow _pagination.next), and every object carries an _links block of related resource URLs so you can traverse from a conversation to its messages, its assignee, or its inbox without hand-building paths.

Webhooks: getting events instead of polling

Polling the conversations endpoint on a timer works, but it's wasteful and always a little behind. Front's webhooks flip that around: they push real-time notifications to a URL you own when specific events happen — a new inbound message, a conversation assigned, a tag added, an archive. You configure them as an event-driven rule action (the webhook Then-action in Front's rules) or as an application trigger if you're building on the app framework.

A webhook payload is a JSON POST describing the event and the affected object, so your endpoint can react immediately — post to Slack, kick off a downstream workflow, or hand the conversation to an agent — without burning rate-limit budget on a polling loop. For anything approaching real time, webhooks are the right primitive; reserve direct endpoint calls for when you then need to act on the conversation the webhook told you about.

The honest limits — and where an AI layer picks up

The Front API is complete and well-documented, and for moving data and firing actions it does exactly what a good REST API should. But it's plumbing, not intelligence, and it's worth being honest about the edges.

The rate limits are real and per-company — a chatty integration on a Starter plan (50 rpm) can starve the rest of your automations, and burst exhaustion means a 10-minute cool-off, so heavy syncs need genuine backoff logic. Token scoping is powerful but easy to under-grant: a 403 on an endpoint that "should" work is almost always a missing permission or wrong namespace, not a server problem. And most fundamentally, the API can fetch a conversation and send a draft, but it has no opinion about what the reply should say — that reasoning is yours to build.

That last gap is exactly the seam where an AI agent layer fits, and it does so through this same API rather than around it. The broader category of AI agents for customer service exists for the reading-and-answering work no endpoint performs on its own. Macha is one such layer: it runs on top of the Front you already use via the live Macha–Front connector, consuming the very conversations, messages, and drafts endpoints described above — it does not replace Front, your inboxes, or your API access. You keep Front and its API doing what they do well: holding the conversations and moving the data. Macha's agent then reads the conversation, understands intent, and pulls a real order or account status through a custom tool that turns your own REST API into something the agent can call — before drafting or sending a grounded reply. And because reasoning has a different cost than a plumbing call, Macha's credits are consumed per AI action, never per resolution.

If you're wiring this up yourself, the companion guide to using the Front API walks through your first authenticated calls step by step, and it pairs naturally with how Front rules and the shared inbox model behave underneath the API.

FAQ

What is the base URL for the Front API? Every Core API request goes to https://api2.frontapp.com. It's a JSON-over-HTTPS REST API, and you authenticate every call with an Authorization: Bearer <token> header.

How do I authenticate with the Front API? Two ways. For testing or a single-customer integration, generate an API token under Settings → Developers → API tokens and send it as a Bearer token. For public or partner integrations that act on other companies' behalf, use OAuth, which Front recommends and often requires for its app framework.

What are Front's API rate limits? They're per-company, not per-token: 50 requests/min on Starter, 100 on Professional, and 200 on Enterprise, with partner OAuth integrations getting a separate 120 rpm. There are also per-resource per-second caps (5 req/sec for conversations, messages, and channels; 1 req/sec for exports) and a burst allowance equal to half your plan limit. Exceeding a limit returns 429 with a retry-after header.

Which Front API endpoints do I actually need? For most integrations: conversations (the central object), messages (send/reply), contacts (sync people), and drafts (suggest replies). Channels, teammates, tags, comments, and analytics cover the rest. Webhooks push real-time events so you don't have to poll.

Can I add AI to Front through its API without replacing Front? Yes. An agent layer like Macha connects to Front as a live connector and uses the same conversations, messages, and drafts endpoints — running on top of your existing inboxes rather than replacing them. Front and its API keep holding and moving the data; the agent reads intent and drafts or sends a grounded reply.

Ready to turn API calls into answered conversations? Start a free trial of Macha and connect it to your Front in minutes.