Authentication

The Cybooks Public API uses the OAuth 2.0 client credentials grant for server-to-server integrations. Create a separate API key for each integration, grant only the scopes it needs, and keep its secret outside source control and client-side applications.

The production API base URL is https://api.cybooks.com.cy/v1, and the token endpoint is https://api.cybooks.com.cy/oauth/token. These are the same URLs shown when you create a key. The older host, https://app.cybooks.com.cy/api/v1 with its token endpoint https://app.cybooks.com.cy/oauth/token, still works until its sunset date (see Deprecations); its responses carry Deprecation, Sunset and a successor Link header that names the same path on api.cybooks.com.cy. Note that the paths differ: the canonical host has no /api prefix.

Create an API key

  1. Open the company the integration will access.
  2. Go to Settings > API and select Create API key.
  3. Name the key and select its permissions. Read, write, and additional abilities such as actions or exports map to OAuth scopes.
  4. Copy the client ID and client secret when they appear.

The client secret is displayed once. Cybooks cannot show it again. If it is lost or exposed, rotate the key and save the new client ID and secret.

Every API key is permanently bound to the company in which it was created. Cybooks derives the company from the credential, so do not send tenant, X-Tenant-Id, company, or X-Company-Id headers. Requests that try to select a different company are rejected.

Request an access token

Exchange the client credentials at https://api.cybooks.com.cy/oauth/token. Send the scopes needed by this token as one space-separated scope value. Every requested scope must have been granted to the API key.

HTTP Basic authentication keeps the client credentials separate from the form body:

curl --request POST 'https://api.cybooks.com.cy/oauth/token' \
  --user "${CYBOOKS_CLIENT_ID}:${CYBOOKS_CLIENT_SECRET}" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'scope=customers:read invoices:read'

The client ID and secret can alternatively be sent as form fields:

curl --request POST 'https://api.cybooks.com.cy/oauth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=${CYBOOKS_CLIENT_ID}" \
  --data-urlencode "client_secret=${CYBOOKS_CLIENT_SECRET}" \
  --data-urlencode 'scope=customers:read invoices:read'

A successful response contains a bearer token and its lifetime:

{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "eyJ..."
}

Treat expires_in as authoritative instead of assuming a fixed lifetime. The client credentials grant does not issue a refresh_token; request another access token with the client ID and secret before the current token expires.

From 2027-01-11, access tokens last 60 minutes. Until then, a new token expires at 2027-01-11 00:00 UTC (and never in less than 60 minutes), so expires_in can be larger than 3600. Tokens issued before 2027-01-11 expire on that date, including older tokens issued with a one-year lifetime. An integration that requests a new token whenever one expires needs no change.

Call the API

Send the access token in the Authorization header:

curl 'https://api.cybooks.com.cy/v1/customers?per_page=25' \
  --header "Authorization: Bearer ${CYBOOKS_ACCESS_TOKEN}" \
  --header 'Accept: application/json'

The security section for each endpoint lists its required scope. A granted OAuth scope is necessary but does not bypass the key owner's current company permissions or the company's enabled features.

Understand authentication errors

  • 401 Unauthorized means Cybooks could not use the credential or token. Common causes are a missing, malformed, expired, revoked, or rotated token; invalid client credentials; a credential past its expiry; a request outside its CIDR allowlist; or asking the token endpoint for a scope the key was not granted.
  • 403 Forbidden means authentication succeeded but the request is not allowed. Common causes are a missing endpoint scope, the key owner no longer having the required company permission or membership, the feature being unavailable, or a forbidden tenant-selection header. When the company's subscription has expired, every API request, reads included, and every token request with valid client credentials answers 403 Forbidden with the code subscription_expired until the subscription is renewed in Cybooks.

At the token endpoint, every rejected client-credentials request gets the same response: the OAuth error invalid_client with status 401 Unauthorized, whatever the reason (unknown client, wrong or missing secret, a revoked or expired key, an address outside the allowlist, or a scope the key was not granted). Only a request with valid client credentials for a key in good standing can get a different refusal, 403 Forbidden in the documented error envelope, about the company rather than the key: subscription_expired when the company's subscription has expired, plan_feature_paused when its plan no longer includes the API, and forbidden when its plan never did. No access token is returned. Repeated failed attempts are rate limited and answered with 429 Too Many Requests. Public API errors use the documented error envelope. Include the response's X-Request-Id when contacting support. On API requests you can send your own X-Request-Id of 8 to 36 characters (letters, digits, ., _ and -, starting with a letter or digit); any other value is replaced by an id Cybooks generates, and the response returns the id that was used.

Expiry and CIDR restrictions

Some API keys may have an administrator-configured expiry time or an allowlist of up to 20 IPv4 or IPv6 CIDR ranges. When these restrictions are present, Cybooks enforces them both when issuing a token and on every API request. Existing tokens therefore stop working immediately when the key expires, is revoked, or is used from an address outside its allowlist.

Cybooks checks the allowlist against the connecting address, which is the address the load balancer sees. Use the integration's stable public egress addresses in a CIDR allowlist. Private container or host addresses are not the source addresses Cybooks sees.

Rotate or revoke a key

Rotate a key from Settings > API if the secret may be exposed or as part of a regular rotation schedule. Rotation creates a new client ID and client secret and immediately revokes tokens and credentials from the previous version. Update both values in the integration before requesting its next token.

Revoking a key immediately invalidates its active access tokens and prevents further token exchanges. Create separate keys for separate integrations so one can be rotated or revoked without interrupting the others.

Retry writes safely

Follow the Idempotency-Key requirement shown on each write endpoint. For endpoints with durable idempotency, send a unique value of at most 191 characters:

curl --request POST 'https://api.cybooks.com.cy/v1/customers' \
  --header "Authorization: Bearer ${CYBOOKS_ACCESS_TOKEN}" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --data '{"company_name":"Example Ltd"}'

Cybooks stores the request hash and successful response for 24 hours for durable idempotent operations; explicitly classified terminal client errors may also be stored. Repeating the same request on the same endpoint with the same key replays the stored response. Reusing that key with different request content, query parameters, or concurrency headers returns 409 Conflict with the code idempotency_conflict. Request content is the JSON body or, for a form-encoded or multipart request, its fields and each uploaded file's name, size, type and content. Keep the same key when retrying after a network timeout. A replay re-checks authorization: a key whose first request succeeded answers 403 Forbidden once the key's user has lost the permission or the company's plan no longer includes the feature, so reconcile with a GET instead of retrying.

Exports and other long-running requests create an operation, which you poll through GET /operations/{id} or the export's own status endpoint. Cybooks never deletes a queued or running operation. A finished operation stays readable until the operation's own expires_at (not the shorter expires_at of a download link), currently 30 days after it was created. Cybooks may delete it, and any export file it produced, at any time after that; reading it then answers 404 Not Found.

Rate limits

Public API traffic is limited in three ways:

  • 60 requests per minute for each access token;
  • 600 requests per minute for each company, shared by every access token of that company and by the operations Claude and other MCP connectors run in it through the Cybooks connector;
  • 5,000 requests per day for each API client and company.

Responses describe the active policy and remaining allowance with RateLimit-Policy, RateLimit-Limit, and RateLimit-Remaining. A 429 Too Many Requests response includes retry timing; wait for Retry-After before trying again. If one integration needs a larger share of the company allowance, spread its work out or contact support.

Each kind of export (ledger, time-log and reimbursement bundle) is also admitted at most three times per five minutes for each API client and company, and a time-log export may hold at most 50,000 rows as CSV or XLSX and 2,000 rows as PDF; a larger one is refused with 422 and the code time_log_export_too_large, so narrow it by date, person or task.

A company can hold at most 25 active API keys. Creating another answers 409 Conflict with the code api_credential_limit_reached; revoked and expired keys do not count, so revoke a key you no longer use first. Rotating a key does not count as a new one.

Receive webhooks

To be told when data changes instead of polling, subscribe to signed webhook events; the Webhooks guide covers subscriptions, signature verification, retries and replays.

Deprecations

A deprecated operation keeps working until its sunset date and says so on every response: Deprecation: true, a Sunset date, and a Link header with rel="successor-version" for each operation that replaces it. The sunset date is the earliest date the operation may be removed; Cybooks removes it only after measured usage shows integrations have moved.

OperationsDeprecatedSunsetUse instead
/contacts (list, get, create, update, archive, restore)2026-09-292027-03-31/customers and /vendors
Client-credentials access tokens valid for one year2026-102027-01-11Request a new token when one expires; tokens last 60 minutes
The app.cybooks.com.cy host (https://app.cybooks.com.cy/api/v1 and its /oauth/token)2026-102027-02-23https://api.cybooks.com.cy/v1 and https://api.cybooks.com.cy/oauth/token

Contacts are the legacy party record from before customers and vendors became separate resources; a 2024 migration moved the contacts that existed then into customers and vendors. To migrate an integration, call GET /contacts?filter[migration_status]=all and read each contact's successor: a migrated contact names the customer or vendor that replaced it, which you then read and update through the customer and vendor endpoints. Create new parties with POST /customers or POST /vendors. A contact without a successor has not been migrated; recreate it as a customer or vendor.