Caching / 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. There is no public live-read URL on this page.

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": {}
  }]
}

No public live-read URL. No live-read host on this page.

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. This page does not document a vendor daily cap.

Retries

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.

Honest delivery

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.

Dedup

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.

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

{
  "status": 422,
  "code": "validation"
}

No “send it anyway and let the PSA reject it.” No extra validation codes on this page.

Credential vault

The MSP pastes their own keys. Those keys sit in a per-tenant vault. The ISV never holds them.

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.

Customer map

A sure match auto-maps. A leftover PSA company with no ISV candidate is an ask: the MSP creates or imports it in the ISV. Ambiguous UNMAPPED is a human match. It is never an auto-create.

Mechanism

Listed identity routes exist: GET /tenants/{tenant_id}/identity/mappings and GET /tenants/{tenant_id}/identity/unmapped.

What the caller sees

Mapped rows when the match is sure. UNMAPPED when a person has to choose. Creating a leftover PSA company in the ISV returns 501 (OPEN).

{
  "status": "UNMAPPED"
}

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

Creating a leftover PSA company in the ISV returns 501. No silent create.

Identity hold

Unmatched records can sit in quarantine until someone releases them.

Mechanism

Hold is a reserved record, not an auto-merge. The reserved shape name is QuarantinedRecord.

What the caller sees

Unmatched work stays unmatched until release. Do not treat this page as a schema for that record.

{
  "status": "UNMAPPED"
}

# Reserved shape: QuarantinedRecord
# Fields are not documented on this page.

Health + incidents + audit

Status and an audit log sit on every connection. After the MSP connects, a role connector attaches so the ISV can see that MSP on health and status. Failed auth attaches nothing. Vendors with no role audit unknown, not success. Incidents are a listed read. Not a new connect UI.

GET /incidents can name which ISV, MSP, and field sit on a moved vendor field. Sandbox seeds one open Autotask incident with that list. That is not the same as one MSP connection going degraded. We do not patch the vendor.

Mechanism

GET /tenants/{tenant_id}/audit exists. Also listed: /status, /incidents, /connections, and /connections/events.

What the caller sees

Audit is a GET on the tenant.

curl -s "$BITLYNC_BASE/tenants/sandbox-mainstreet/audit" \
  -H "X-API-Key: $BITLYNC_KEY"

GET /tenants/{tenant_id}/audit
GET /tenants/{tenant_id}/status
GET /tenants/{tenant_id}/incidents

No public ops host on this page.

Raw

The canonical Bitlync shape is the default. The vendor payload always rides on raw.

Mechanism

Normalize status, source, and the other Bitlync words. Keep the vendor’s original object under raw. Never drop it.

What the caller sees

You can stay on the canonical fields. You can read raw when a vendor word is not in the model.

{
  "status": "in_progress",
  "source": "psa",
  "raw": {}
}

No mode that strips raw. No second public schema that replaces the canonical default.

Writes

dry_run defaults true. That is a preview with no side effect. Commit by sending dry_run false. After Bitlync creates a ticket, you can update it, append a note, close with evidence, or POST hours on that ticket only. Close stays off unless the MSP turns it on. Hours take stated billable and an optional member. No notes on time. Not a time read. Not two-way. Not field-level ticket sync.

Mechanism

Preview first. Then commit with the same body and an idempotency_key on writes that support it. 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",
  "dry_run": true,
  "idempotency_key": "ticket-1"
}

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

Ticket create, write-back, and time run on fixtures and dry_run for ConnectWise, Halo, and Autotask. dry_run defaults true. Halo pulls agreements and line items, the same objects as ConnectWise and Autotask. ConnectWise, Autotask, and Halo write line items on an existing agreement: add, rewrite, end, replace. ConnectWise, Autotask, and Halo pull the project container and write on an existing project. We do not mint a project header. Baseline cannot take that write. Creating a leftover PSA company in the ISV returns 501. Pax8 matches a company it already has, then creates the rest.

The MSP can approve or dismiss a mapped line item. Approve writes the line on an existing agreement. Dismiss does not change the agreement. ConnectWise only.

What we write lists the locks and refusals.

Sandbox

Seeded fixtures only: sandbox-mainstreet and sandbox-northline. Use $BITLYNC_BASE as the host placeholder. There is no public sandbox host on this page.

Mechanism

Every sandbox response includes sandbox true. POST /sandbox/reset with that tenant id clears audit, re-syncs fixtures, and writes one sandbox_reset event. A production tenant on that route returns 422 request_invalid.

What the caller sees

{
  "sandbox": true,
  "served_from": "store"
}

POST /sandbox/reset
{ "tenant_id": "sandbox-mainstreet" }

HTTP 422
{
  "status": 422,
  "code": "request_invalid"
}

Seed also includes one open Autotask incident with a fixture affected list. Northline Halo degraded is a separate connection status.

No public sandbox URL. No production host printed here. Connectors on this site run against a seeded sandbox, not a production AWS tenant.

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

HTTP 401  { "status": 401, "code": "auth" }
HTTP 403  { "status": 403, "code": "tenant" }
HTTP 404  { "status": 404 }
HTTP 422  { "status": 422, "code": "validation" }
HTTP 429  Retry-After: 12
HTTP 501  { "status": 501, "code": "unsupported" }
HTTP 500  { "status": 500, "code": "internal_error" }

No extra codes on this page. 500 stays opaque. A parked write is 501, not a generic 500.

MSP permission / probe

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

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.”

Routing

A finding lands as a PSA ticket until the MSP chooses otherwise. The ISV does not force workflows.

Mechanism

Listed routes: POST /tenants/{tenant_id}/findings/route and GET / PUT /tenants/{tenant_id}/routing. Alert to ticket is the path. Incident and approval sit on that same path.

What the caller sees

The finding becomes a ticket in the PSA the MSP already runs. Routing changes are the MSP’s.

POST /tenants/{tenant_id}/findings/route
GET  /tenants/{tenant_id}/routing
PUT  /tenants/{tenant_id}/routing

{
  "source": "psa",
  "raw": {}
}