PSA Integrations

PSA (Professional Services Automation) integrations connect Breeze to the ticketing platform your service desk already runs on. Once a connection is configured, Breeze can create and sync tickets, tie alerts and devices to external work items, and keep ticket status flowing in the direction you choose. PSA is the most fully featured integration type in Breeze: connections are database-backed with encrypted credential storage, per-connection sync settings, and ticket mapping.

You manage PSA connections from Integrations → PSA. The tab is deep-linkable at /integrations#psa.

Note

PSA connections are backed by a dedicated database table with encrypted credential storage. Credentials are encrypted at rest using AES-256-GCM before they are written to the database, and they are never returned in API responses — only a hasCredentials indicator is exposed.

---

Supported Providers

Breeze supports six PSA providers. Pick one when you create a connection; each provider has its own set of relevant credential fields.

Provider	Instance URL example
Jira	https://your-domain.atlassian.net
ServiceNow	https://instance.service-now.com
ConnectWise	https://api-na.myconnectwise.net
Autotask	https://webservices.autotask.net/atservices/1.6/atws.asmx
Freshservice	https://your-domain.freshservice.com
Zendesk	https://your-domain.zendesk.com

Not every credential field applies to every provider. Fill in the ones your provider needs and leave the rest blank — for example, Jira uses an email/username plus an API token, ConnectWise uses a public/private key pair, and ServiceNow uses a username and password. The instance URL placeholder in the form updates to match the provider you select.

---

Connecting a PSA Platform

1. Open Integrations → PSA (or go straight to /integrations#psa) and click Add connection.

2. Give the connection a name (for example, “ConnectWise — Contoso”) and choose the provider from the dropdown. A short hint under the provider field describes the credentials that provider expects.

3. Under Connection details, enter the Instance URL for your PSA platform and, optionally, a Default queue (the board, queue, or project that new tickets land in).

4. Under Credentials, fill in the fields your provider requires — any combination of Username, Password, API Token, Client ID, and Client Secret. Secret fields are masked; use the eye toggle to reveal what you typed. Only the fields relevant to your provider need values.

5. Under Sync settings, decide how tickets sync (see Ticket Sync & Field Mappings below).

6. Click Create connection. Breeze encrypts the credentials and saves the connection.

7. Open the connection again in Edit mode and click Test connection to verify the credentials are valid (see Testing a Connection).

Caution

In production the APP_ENCRYPTION_KEY environment variable must be set — the API refuses to start without it, because it is the key used to encrypt PSA credentials at rest. If credential encryption fails, connection creation returns a “Failed to encrypt credentials” error.

Credentials You May Need

Field	Used for
Instance URL	The base URL of your PSA platform
Default queue	The board / queue / project new tickets are created in
Username	Login or email for providers that authenticate with a user identity
Password	Password for providers that authenticate with username + password
API Token	Token-based authentication (e.g. Jira, Zendesk, Freshservice)
Client ID	OAuth / API client identifier where the provider requires one
Client Secret	OAuth / API client secret

Note

When you edit an existing connection, credential fields are shown blank with a “keep existing” hint. Leave a secret field empty to keep the stored value unchanged; type a new value only when you want to rotate it. Credentials are replaced as a whole — partial credential updates are not supported.

---

Testing a Connection

The Test connection button is available when you edit an existing connection. It sends a live request to the PSA platform using the stored credentials and reports the result in a dialog:

• On success, Breeze shows a confirmation and records the test outcome on the connection (a lastTestedAt timestamp and a verified status).
• On failure, Breeze shows the error returned by the provider along with a prompt to re-check your credentials and instance URL.

Tip

If you just created a connection, reopen it with Edit to reach the Test connection button. Testing before you rely on sync catches bad credentials, an incorrect instance URL, or a provider that requires IP allowlisting for API access.

---

Managing Connections

The PSA tab lists every connection with its provider, name, status, and last-sync time. You can search connections by name or provider and filter by status. Each row offers these actions:

Action	What it does
Edit	Open the connection to change its name, credentials, or sync settings, or to test it
Sync now	Trigger a manual data sync immediately
Pause / Resume	Toggle the connection between active and paused — a paused connection stays configured but stops syncing
Delete	Remove the connection permanently

Connection status is one of:

Status	Meaning
Active	The connection is enabled and syncing
Paused	Syncing is temporarily disabled; the connection and its credentials are retained
Syncing	A sync is currently in progress
Error	The most recent sync or test failed

Caution

Deleting a connection also removes all of its associated ticket mappings. This action cannot be undone. If the connection is currently active, Breeze warns you before deleting.

---

Ticket Sync & Field Mappings

Each connection carries its own sync settings, configured under Sync settings when you create or edit it.

Setting	Options	Purpose
Enable sync	On / Off	Master switch for automatic syncing on this connection
Sync interval	Every 15 minutes, 30 minutes, hourly, every 6 hours, daily	How often Breeze runs an automatic sync
Sync direction	Inbound, Outbound, Bidirectional	Which way ticket data flows between Breeze and the PSA
Auto-close / sync on close	On / Off	Keep ticket close state in sync between the two systems
Include notes	On / Off	Carry ticket notes across during sync

The interval, direction, auto-close, and notes controls are only editable while Enable sync is on.

Sync direction

• Inbound — ticket data flows from the PSA into Breeze.
• Outbound — Breeze pushes ticket data out to the PSA.
• Bidirectional — changes sync both ways (the default).

Ticket mappings

As tickets sync, Breeze records ticket mappings that tie a Breeze entity to the corresponding external ticket. A mapping tracks the external ticket ID and URL, the current ticket status, the last sync time, and — where applicable — the associated Breeze alert or device. The PSA tab surfaces recent ticket mappings below the connection list so you can see what has synced. Mappings are created during sync operations, so a brand-new connection will not show tickets until it has synced at least once.

Note

Because mappings can carry an alertId or a deviceId, a synced ticket stays linked to the alert that raised it or the device it concerns — deleting the connection removes those mappings along with it.

---

Troubleshooting

Connection test fails. Confirm the credentials are correct and that the PSA platform’s API is reachable from your Breeze API server. Some providers require IP allowlisting or VPN access. Double-check the instance URL matches the provider format shown in the form, and re-check any secret fields you may have left blank on edit.

“Failed to encrypt credentials” when saving a connection. The APP_ENCRYPTION_KEY environment variable is not set or is invalid. In production this variable is required and the API will not start without it. On Breeze-hosted accounts this is already configured.

Editing a connection wiped my credentials. Credentials are replaced as a whole, not merged. On the edit form, leave a secret field blank to keep its existing value — only type into it when you intend to rotate that credential.

No tickets are showing up. Ticket mappings appear only after a sync has run. Use Sync now on the connection to trigger one, and make sure Enable sync is on. If the connection status is Paused or Error, syncing will not run until you resume it or resolve the error.

A connection shows the Error status. The most recent sync or test failed. Open the connection, run Test connection to see the provider’s error message, and correct the credentials or instance URL as needed.

---

Related

• Integrations overview — the full Integrations page, including communication, monitoring, accounting, distributor, and network integrations.
• Ticketing — Breeze’s native ticketing system that PSA connections sync against.
• Webhooks — push real-time event notifications to external systems, including your PSA or messaging tools.