Store-served reads

Reads come from the synced store for that MSP tenant. One sync fills the store. Every ISV on that tenant reads the same copy.

Mechanism

The caller asks for tickets, devices, or other listed reads. Bitlync answers from the store. That path does not spend vendor budget. live=True is an opt-in live read when a store read is not enough.

What the caller sees

The response names the store and the last sync. Fields are served_from and last_synced_at.

{
  "served_from": "store",
  "last_synced_at": "2026-07-11T14:03:22Z",
  "data": [{
    "status": "in_progress",
    "source": "psa",
    "raw": {}
  }]
}

Every canonical object includes vendor: { connector, native_id, native }. native is the same payload as .raw. .raw is read-only.

Rate limits

We pace writes to the vendor’s real limit. If we have to wait, you get a rate-limit response (HTTP 429) with Retry-After. You do not guess a vendor quota.

One sync per MSP tenant fills the store. Every product on that tenant reads the same copy. When each product polls the same PSA, they share one budget.

Mechanism

ISV-facing: 600 req/min times the number of connected MSPs. There is no daily cap. The per-minute rate is the limit. Hit it and you get a rate-limit response with Retry-After. There is no silent throttle.

What the caller sees

A rate-limit response you can branch on. The header is the wait. Do not treat a delayed 200 as a throttle.

HTTP 429
Retry-After: 12

{
  "status": 429
}

No silent queue that looks like success.

Delivery

Transient vendor rate limits (429) and 503 are retried with backoff on the Bitlync side of the write.

Mechanism

The caller sends one write. Bitlync retries the vendor when the failure is transient. The caller is not asked to implement vendor backoff for those hops.

What the caller sees

The caller sees one result. If the write still cannot land, the final rate-limit response (429) still carries the vendor Retry-After.

HTTP 429
Retry-After: 30

{
  "status": 429
}

No hidden swallow of a vendor rate limit (429). No rewrite of a final rate limit into a 200.

Delivery status is visible. Nothing is dropped silently.

Mechanism

A write that was acknowledged cannot double-write. A write that was throttled is a real rate-limit response (429), not a delayed success. Dedup and retries sit on this same rule.

What the caller sees

Success means the write landed or was an idempotent replay. Throttle means a rate-limit response (429) plus Retry-After.

{
  "idempotent_replay": false
}

No silent drop. No “accepted” that later vanishes.

Writes that support it take idempotency_key. The same key does not open a second ticket.

Mechanism

Send the key on the write. A retry with that key is a replay, not a new vendor create.

What the caller sees

The replay is marked idempotent_replay.

{
  "summary": "Printer offline",
  "dry_run": false,
  "idempotency_key": "ticket-1"
}

{
  "status": "ok",
  "idempotent_replay": true
}

Keys are not implied on every future write. Only writes that already support idempotency_key.

Ticket, device, and company events: list with GET /tenants/{id}/connections/events or a signed webhook. Grants psa.ticket.events, rmm.device.events, psa.company.events. Missing is grant_missing.

Writes

dry_run defaults to false, so a write is real. Test writes in the sandbox. Optional: dry_run true checks a write against a new MSP's setup without creating a record. After Bitlync creates a ticket, you can update it, append a note, close with evidence, or POST hours on that ticket only. You can close a ticket once they accept the connection. Auto-close when a finding is fixed is a separate switch. Closing is the MSP's call. On Configure, under Ticketing, the MSP turns on "Allow closing tickets with a resolution" for that connection; it is off by default. On, a close_with_resolution write closes the ticket in your stack with the resolution note. Off, the resolution lands as a note and the ticket stays open. Ticket create and update on ConnectWise and Halo accept board, status, and priority ids from GET /tenants/{id}/ticket-boards, ticket-statuses, and ticket-priorities; unknown id returns 422. Hours take stated billable and a member id from the PSA list. ConnectWise and Halo list members for the time picker. No notes on time. Not field-level ticket sync.

Mechanism

Writes are real by default. Send an idempotency_key on writes that support it; dry_run true checks first without creating a record. If a fan-out is only partial, that failure is explicit. It is never collapsed into a single silent success.

What the caller sees

A dry run does not create a ticket. A commit does. Partial failure is visible on the response, not hidden.

{
  "summary": "Printer offline",
  "idempotency_key": "ticket-1"
}

// optional check, no record created
{
  "summary": "Printer offline",
  "dry_run": true,
  "idempotency_key": "ticket-check-1"
}

Halo, ConnectWise, and SuperOps ticket create, update, close, reopen, and notes commit when dry_run is false. ConnectWise and Halo time entries commit when dry_run is false. Halo pulls agreements and line items, the same objects as ConnectWise. ConnectWise and Halo update the quantity on a line item the MSP matched on an existing agreement. We never create agreements or line items. SuperOps reads companies, tickets, and agreements. Billing quantity updates are not available for SuperOps. ConnectWise and Halo pull the project container and write on an existing project. We do not mint a project header. Some connectors cannot take that write. ConnectWise and Halo list ticket statuses, boards, and priorities live and enrich ticket display; ticket create and update accept those list ids (unknown id returns 422). ConnectWise and Halo list members for the time picker. When company import from PSA is available, Import creates a leftover in the ISV after preview (bulk Import unmatched uses the same path). When that write is unavailable, Import returns 501. We never create the company in the PSA. Pax8 matches a company it already has, then creates the rest.

The MSP can approve or dismiss a mapped line item. Approve updates the quantity on the matched line of an existing agreement. Dismiss does not change the agreement. ConnectWise and Halo.

What we write lists the locks and refusals.

Validation

The payload is checked against that vendor’s rules before it leaves Bitlync.

Mechanism

A bad field fails on the request you sent. It does not create a ticket.

What the caller sees

HTTP 422. Branch on stable code validation.

HTTP 422

{
  "code": "validation",
  "message": "The request did not validate.",
  "doc_url": "https://docs.bitlync.com/concepts/errors/"
}

No “send it anyway and let the PSA reject it.”

Credential vault

The MSP pastes their own keys. Those keys sit in a per-tenant vault. The ISV never holds them. We stamp when keys land. No connect, no keys.

Mechanism

ISVs start with a key that looks like blk_… and header X-API-Key. MSP credentials are entered on Bitlync, not in your frontend.

What the caller sees

Your product sends X-API-Key. It does not send the MSP’s PSA or RMM secret.

X-API-Key: blk_…

# MSP keys are not in this header.
# They sit in the per-tenant vault.

The ISV does not paste MSP creds. There is no shared-secret path that puts PSA keys in your app.

Exact-name auto-Match fills Match when a leftover PSA company name uniquely matches an existing ISV customer — Match only, never auto-import. A leftover ask is Match, company import from PSA, Skip, or Needs match. Bulk unmatched import is available with dry_run preview. Ambiguous UNMAPPED is a human match. It is never an auto-create or auto-import.

Errors

Branch on the stable code. Do not parse a human sentence.

Mechanism

The codes on this page are the codes that exist: 401 auth, 403 tenant, 404 unknown tenant, 422 validation (and request_invalid on a bad sandbox reset), 429 plus Retry-After, 501 unsupported / parked capability, 500 opaque internal_error.

What the caller sees

The body is code, message, and doc_url. details is optional.

{
  "code": "validation",
  "message": "The request did not validate.",
  "doc_url": "https://docs.bitlync.com/concepts/errors/"
}

500 stays opaque. A parked write is 501, not a generic 500.

Health, incidents, and audit are listed reads on Reference, not a new UI.

MSP permissions

A missing write permission can still connect as partial. Reads work. The parked write is refused distinctly. That is not a generic 500.

ConnectWise, Halo, and SuperOps connect are numbered click paths in the flow. Halo pastes a client ID, client secret, and the two server URLs. If a permission is missing, we name it in English. We never create companies or agreements in the PSA; the MSP creates them. Company custom-field write (grant psa.company.update) is off by default; on when the MSP enables it. We always match first. If two records match, we refuse.

Mechanism

The MSP pastes keys in the guided flow. The probe names the permission to fix. The ISV does not paste MSP creds.

What the caller sees

Reads still serve from the store. A parked write is 501 unsupported. Portal copy tells the MSP which permission to fix.

HTTP 501
{
  "status": 501,
  "code": "unsupported"
}

# Portal copy names the permission.
# ISV does not paste MSP creds.

No ISV-side form that collects PSA keys. Partial connect is not collapsed into “failed.”