Authentication

Every /v1 request is authenticated with an API key and targeted at one connection (a paired GP install) and one company (a GP company database).

API keys

Create keys in the dashboard under API Keys. The full key is shown once on creation — store it securely; only a sha256 hash is kept server-side.

Send the key as a bearer token:

curl https://api.erpspan.com/v1/customers \
  -H "Authorization: Bearer $LB_LIVE_KEY" \
  -H "X-Connection-Id: conn_..."

Scopes

A key carries one or more scopes; a request is refused 403 FORBIDDEN without the right one.

Rotating a key

POST /v1/api-keys/{id}/rotate replaces a key's secret in place — same key id, name, mode, and scopes. The response carries the fresh secret exactly once (like creation, only a sha256 hash is kept server-side), and the previous secret stops working immediately.

curl -X POST https://api.erpspan.com/v1/api-keys/key_.../rotate \
  -H "Authorization: Bearer $LB_LIVE_KEY"

{ "key": { "id": "key_...", "name": "prod", "prefix": "lb_live_a1b2", "mode": "live",
    "scopes": ["read", "write"], "revokedAt": null, "createdAt": "2026-07-10T12:00:00Z" },
  "secret": "lb_live_…" }

• The calling key needs the write scope (rotation is a management action) — 403 FORBIDDEN without it.
• A key may rotate any key in its own organization, including itself — the new secret is returned to the caller.
• A key that is unknown, revoked, or belongs to another organization is a uniform 404 NOT_FOUND.
• Creating, listing, and revoking keys stay in the dashboard; rotation is exposed on the API for automated key hygiene.

Connection & company targeting

• X-Connection-Id: conn_… selects which paired GP install to talk to. It is required on every /v1/{object} route — a missing header is 400 VALIDATION_ERROR.
• A lb_test_ key with no X-Connection-Id is automatically routed to your org's sandbox, so the quickstart works with no headers at all.
• X-Company: <INTERID> selects the GP company database. It's optional — it defaults to the connection's default company. A company the connection doesn't have is 400 VALIDATION_ERROR.

Keys, connections, and companies are all scoped to your organization: a key can only ever reach connections your organization owns.