> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Front

> Connect Front, the shared-inbox customer communication platform, to Serval so workflows can manage conversations, contacts, inboxes, tags, and more through the Front API.

## About Front

Front is a customer communication platform built around shared inboxes for email, chat, SMS, and social channels. Serval connects to your Front workspace with a single Front API token, stored encrypted and attached automatically to every request Serval makes to the Front API. One connection covers both of Front's API surfaces: the Core API (conversations, contacts, inboxes, tags, teammates, templates, knowledge bases, analytics, and rules) and the Channel API (custom channel messaging).

**Authentication:** Front API token, pasted into Serval's connect form. There is no OAuth redirect and no client secret to manage.

**Data sync:** On-demand only. Serval does not run background syncs, does not ingest Front webhooks, and installs no prebuilt workflows - data is read and written at the moment a workflow runs.

## What the Front integration enables

| Capability                                  | Description                                                                                                                                                                  |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Manage conversations                        | List, search, read, and update conversations; manage assignees, followers, inboxes, links, tags, comments (including replies and mentions), drafts, messages, and reminders. |
| Work with contacts and accounts             | Create, read, update, and merge contacts; manage contact handles, notes, groups, and lists; manage accounts, account contacts, and custom fields.                            |
| Administer inboxes, channels, and teammates | List and manage inboxes, channels, teammates, teammate groups, teams, shifts, signatures, and views; import messages into inboxes; create channel drafts and messages.       |
| Tags, rules, and statuses                   | Create and manage tags (including child tags and tagged conversations), company and teammate rules, and company statuses.                                                    |
| Message templates                           | Manage message templates and template folders at company, team, and teammate level, including attachment downloads.                                                          |
| Knowledge bases                             | Read and manage knowledge bases, categories, and articles, including per-locale content and article attachments.                                                             |
| Analytics and events                        | Create and fetch analytics exports and reports; list and read workspace events.                                                                                              |
| Custom channel messaging                    | Send inbound and outbound messages on custom channels, manage application message templates, and update message delivery status through Front's Channel API.                 |

Anything defined in the [Front API](https://dev.frontapp.com/reference) can be accessed through Serval.

## Get your credentials

Serval connects with a Front API token, which you generate from the Front dashboard. The token's scopes and permissions are set in Front when you create it, and they determine which resources Serval workflows can reach. See Front's [authentication guide](https://dev.frontapp.com/docs/authentication) for full details.

<Steps>
  <Step title="Open Front settings">
    Log in to your Front account at [app.frontapp.com](https://app.frontapp.com) and open **Settings**.
  </Step>

  <Step title="Go to API Tokens">
    Navigate to **Developers** and open the **API Tokens** tab.
  </Step>

  <Step title="Create a new token">
    Click **Create API token** and give it a descriptive name, such as "Serval Integration".
  </Step>

  <Step title="Select features, scopes, and permissions">
    Choose what the token can reach. At minimum, enable the **Access resources** feature with the **Shared resources** scope for the workspaces Serval should access, plus the read/write/delete/send permissions your workflows will need.
  </Step>

  <Step title="Copy the token">
    Copy the generated token and keep it somewhere safe until you finish connecting.
  </Step>
</Steps>

<Note>
  If you lose the token before connecting, you do not need to start over: Front lets you reveal or copy a token's value again from its details page under **Settings** > **Developers** > **API Tokens**.
</Note>

<Tip>
  Pick scopes generously enough to cover everything your workflows will do. A token with missing scopes can still connect and pass the health check, but specific workflow calls can be denied later.
</Tip>

## Connect in Serval

<Steps>
  <Step title="Open the Front connect form">
    In Serval, add a new Front connection. The form has a single field.
  </Step>

  <Step title="Paste your API token">
    Enter your token in the **API Token** field. It is marked required with a trailing asterisk and rendered as a masked password input. The helper text reads: "Your Front API token. You can generate one from Settings > Developers > API tokens in your Front dashboard."
  </Step>

  <Step title="Save the connection">
    Submit the form. Serval stores the token encrypted and uses it to authenticate every Front request your workflows make.
  </Step>
</Steps>

<Warning>
  Serval does not test the token against Front when you connect, and the form does not block an accidental blank submission - whatever you submit is stored as-is. Double-check that you pasted the full token, then run the health check (below) right after connecting to confirm it actually works.
</Warning>

<Note>
  When editing an existing Front connection, always paste the complete API token before saving - do not save while the field is blank and do not save with the pre-filled masked value still in place. After any edit, re-run the health check to confirm the connection still works.
</Note>

## Verifying the connection

The Front integration ships one health check.

**Validate Front API Connection** - asks Front to identify who the token is authenticated as. On success it reports:

"Successfully connected to Front API. Authenticated as \[first name] \[last name] (\[email])."

On failure it reports:

"Unable to connect to Front API. Please verify your API token is valid and has the necessary permissions."

<Tip>
  A green health check confirms the token authenticates, not that it can reach everything. Front tokens carry their own scopes, so a workflow can still be denied on specific resources even when the check passes. If a workflow call is denied, create a new token in Front with the missing scopes and update the connection.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Re-enter the full token whenever you edit the connection">
    When you open the connection settings, treat the credential as something you must re-supply. Always paste the complete API token before saving any change to the Front connection - never save while the field is empty or still showing the masked placeholder, or the integration can silently stop working. Run the health check after every edit.
  </Accordion>

  <Accordion title="Connecting does not validate the token">
    Serval performs no test call against Front at connect time, so an invalid or revoked token is accepted and saved without complaint. The problem only surfaces when the Validate Front API Connection health check or a workflow call fails. Run the health check immediately after connecting.
  </Accordion>

  <Accordion title="Health check passing does not guarantee scope coverage">
    The health check only verifies that the token authenticates. A token can pass yet be denied on specific resources your workflows use because its scopes were set too narrowly in Front. If that happens, create a new token in Front with the missing scopes and update the connection, re-entering the full token.
  </Accordion>

  <Accordion title="The saved token displays as bullet characters">
    When you revisit the connection, Serval shows the token as bullets plus its last 4 characters, with a control to replace it. This is a display-only mask - Serval never reveals the full token again. To rotate the token, use the replace control, paste the complete new token, and save; if you need to see a token's value, reveal it from the token's details page in Front instead.
  </Accordion>

  <Accordion title="Only Front's standard API service is supported">
    Serval authenticates requests only to Front's official API host (api2.frontapp.com). There is no per-region or custom-domain configuration - all workflow calls, for both the Core API and the Channel API, go to that one service.
  </Accordion>

  <Accordion title="Lists come back one page at a time">
    Front returns list data in pages with a next-page cursor rather than page numbers. A single workflow call retrieves one page of records, and the workflow must follow the next-page cursor until it is absent to gather the full set. If a workflow seems to be missing records, check that it pages through all results.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Front integration.