Authentication

Authenticate with OAuth 2.0

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. When Cybooks support has suspended the company, the same requests answer 403 Forbidden with the code company_suspended until support lifts the suspension; contact Cybooks support. A suspension outranks an expired subscription. The company's keys are kept and work again once it is lifted. When the company asks everyone to use two-factor and the key's owner is past the date without setting it up, every API request and every token request made with that person's keys answers 403 Forbidden with the code two_factor_setup_required until they set two-factor up in Cybooks; the keys are not revoked.

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: company_suspended when Cybooks support has suspended the company, subscription_expired when the company's subscription has expired, plan_feature_paused when its plan no longer includes the API, forbidden when its plan never did, and two_factor_setup_required when the company asks everyone to use two-factor and the key's owner is past the date without setting it up. 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.

Understand validation errors

A request Cybooks cannot accept answers 422 Unprocessable Entity with the type validation_error. When a field fails validation the code is validation_failed, error.message names the first failing field and what is wrong with it (line_items.0.discount: must be at least 0, plus how many more fields failed), and error.fields lists every failing field with a message per failed rule:

{
  "error": {
    "type": "validation_error",
    "code": "validation_failed",
    "message": "line_items.0.discount: must be at least 0 (and 1 more field; see error.fields)",
    "fields": {
      "line_items.0.discount": ["Must be at least 0."],
      "line_items.0.quantity": ["Must be a whole number."]
    }
  }
}

The text says what the field expects (a number, a whole number, a date, one of a short list of values, a length or a range, or that it is required). It never repeats what you sent, and a reference to a record (an id that must exist) always reads The value is not available., the same for a record that does not exist and one that belongs to another company. Any other rule reads The value is invalid. Some refusals carry their own code and message instead, such as invoice_number_taken or adjustment_unit_price_not_accepted. The Cybooks MCP connector returns the same error object in its tool result, with the status in response.status, and the message in the tool's error text.

Every refused request is also logged on our side with the operation, the company, the code, the field names and the failed rule types (never the values), so a request_id from the error is enough for support to find the cause.

Through MCP, a path parameter such as the {id} of GET /bank-transactions/{id}/booked-transactions is a top-level argument of the capability, under the name cybooks_describe_capability gives it. A missing, empty, misnamed (for example transactionId sent for id) or non-string path parameter is refused with 422 before the operation runs: error.fields names the parameter (This field is required. or This value must be a string.), and names any argument the capability does not accept (This argument is not accepted.). Nothing is written and an idempotency_key sent with it can be reused. cybooks_validate_payload gives the same field errors without running the operation.

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.

Update with an ETag (Cybooks-If-Match)

Every resource you can change returns its version in the ETag response header, for example "3f2a9c-v4". Writes that change an existing resource take that value back as a precondition, so you never overwrite a change you have not seen. Send it in the Cybooks-If-Match header:

curl --request POST 'https://api.cybooks.com.cy/v1/invoices/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/approve' \
  --header "Authorization: Bearer ${CYBOOKS_ACCESS_TOKEN}" \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: 7d3c1a2e-5f60-4b8e-9a41-0c2d6e8f1b37' \
  --header 'Cybooks-If-Match: "3f2a9c-v4"'

Send Cybooks-If-Match, never the standard If-Match. Where an endpoint description says If-Match, it means this header. Some HTTP intermediaries evaluate a standard If-Match themselves and can answer 412 Precondition Failed even though Cybooks applied the change. Intermediaries leave Cybooks-If-Match alone, so only Cybooks evaluates it. A request that already sends the standard header is still read with the same meaning, so nothing breaks, but it carries that risk.

  • A successful write returns the resource's new ETag; use it for the next write.
  • A stale value answers 412 Precondition Failed with the code precondition_failed and changes nothing: read the resource again and retry with its current ETag.
  • A missing value on an endpoint that requires one answers 428 Precondition Required with the code precondition_required and the message "Send the resource's ETag in the Cybooks-If-Match header, from your last read of it. Where the operation accepts it, a bare * (one asterisk, without the quotes an ETag has) writes whatever the current version is, without checking that it is unchanged."
  • * (one asterisk, sent bare: Cybooks-If-Match: *, never "*" with the quotes an ETag has, which is an ordinary ETag and answers 412) matches any version: the write goes ahead whatever changed since you last read the resource. Prefer the ETag of your read, which is what stops you overwriting a change you have not seen; send * only when you mean to write over whatever is there. Most writes accept it. These refuse it with 412 Precondition Failed, because each must act on exactly the version you saw: bankRule.order.update (PUT /bank-rules/order), memory.forget, periodLock.close and periodLock.open, and the transfer commits transfer.createManual, transfer.match, transfer.match.confirm and transfer.unmatch.
  • Send Cybooks-If-Match only, never both headers: a standard If-Match on the request can still turn a successful write into a 412 from an intermediary. Sending both with different ETags answers 400 Bad Request with the code conflicting_precondition_headers and changes nothing (a weak W/"…" ETag is a different value from its strong form; spacing and a repeated ETag are not). Send one ETag: a list of several never matches. A request without a valid access token gets its 401 first, and the 400 counts against your rate limit.

Through MCP the ETag goes in the if_match argument (an MCP result carries a read's ETag as response.etag), with the same rules, * included; cybooks_describe_capability describes if_match and idempotency_key for each capability. A commit after a preview sends the Idempotency-Key (MCP: idempotency_key) its preview was sent with: the preview's confirmation token is bound to that key, and a commit with another key is refused with 422.

For idempotency, Cybooks fingerprints Cybooks-If-Match and If-Match the same way, so a retry with the same Idempotency-Key and the same ETag matches the stored request whichever header carries it. Only a retry that sends Cybooks-If-Match reliably gets the replayed response back, though: a retry with a standard If-Match can be answered with a 412 by an intermediary again. Retry with Cybooks-If-Match.

Rate limits

Public API traffic is limited in three ways:

  • 300 requests per minute for each access token;
  • 1,200 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;
  • 50,000 requests per day for each API key and company.

Cybooks AI itself (Ask Cybooks in the app, Cybooks on WhatsApp and the work it runs for you) counts against the same per-company minute, and also against its own share of it: by default half of that per-company minute, and always less than all of it, so Cybooks AI never takes the whole allowance your own integrations use. Your API clients and MCP connectors are never counted against that share.

The per-minute windows start with the first request in them. An API key's day is the calendar day in Cyprus time (Europe/Nicosia): its count resets at midnight there, and rotating the key's secret keeps it. MCP connectors (AI apps) have no daily limit, only the per-token and per-company minutes, so the RateLimit-Policy on their calls carries no daily entry.

Responses describe the active policy and remaining allowance with RateLimit-Policy, RateLimit-Limit, and RateLimit-Remaining. A 429 Too Many Requests response has the code rate_limited, names the limit it hit and says when to retry: the Retry-After header (plus X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset from the named limits above), and an error.rate_limit object:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "The client_per_day rate limit (50000 requests a day for this API key and company, reset at midnight Cyprus time) has been exceeded. Retry in 3600 seconds, at 2026-10-18T21:00:00Z.",
    "fields": [],
    "request_id": "6f1c2a52-6d2e-4f6b-9d0e-1a2b3c4d5e6f",
    "retryable": true,
    "rate_limit": {
      "limit": "client_per_day",
      "max_requests": 50000,
      "window_seconds": 86400,
      "remaining": 0,
      "retry_after_seconds": 3600,
      "reset_at": "2026-10-18T21:00:00Z"
    }
  }
}

limit is token_per_minute, tenant_per_minute, brain_tenant_per_minute (Cybooks AI's share of the company's minute) or client_per_day; another limit, such as export admission, answers other with only the retry timing. Wait retry_after_seconds before trying again. The Cybooks MCP connector returns the same rate_limit object, and the same message, in its tool error; there the daily limit is per API client and company. 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.


Did this page help you?