API

Authentication

API keys for your own software, OAuth for apps people connect, the scopes either can hold, and the plan features and credits endpoints need.

API keys

An Owner or Admin makes keys under Settings, API keys, when the plan includes API access. A key has a name, the scopes you choose, and an expiry: 30, 90, 365 or 730 days, or never. The secret, xbk_ and 43 characters, is shown once. Keep it on your server: never in a browser, an app you ship, or a repository.

Every request

curl https://api.flipbird.io/api/v1/documents \
  -H "Authorization: Bearer xbk_…"
  • A key acts for the member who made it. It can hold only scopes that member holds, and it can never do more than their role allows now: if their role changes, the key's reach changes with it.
  • If that member is deactivated, the key answers 403 key_owner_deactivated until they are reactivated. If they leave the workspace, it answers 403 key_owner_removed: make a new one.
  • Rotating a key makes a new secret with the same name, scopes and expiry, and stops the old secret at once, with no overlap. Revoking stops it for good.
  • A key that is expired, revoked or malformed answers 401 unauthenticated.

OAuth 2.1

An app that acts for whoever connects it uses OAuth 2.1 with the authorization code flow and PKCE. Clients are public: there is no client secret, and the token endpoint refuses client authentication. Each person chooses their workspace, signs in there, and approves the scopes you ask for. Each member sees and revokes the apps they connected under Your account; Owners and Admins see every one in the workspace under Settings, Connected apps.

EndpointURL
Authorization server metadatahttps://api.flipbird.io/.well-known/oauth-authorization-server
Protected resource metadatahttps://api.flipbird.io/.well-known/oauth-protected-resource/api/v1
Client registrationhttps://api.flipbird.io/oauth/register
Authorizationhttps://api.flipbird.io/oauth/authorize
Tokenhttps://api.flipbird.io/oauth/token
Revocationhttps://api.flipbird.io/oauth/revoke

1. Register your client once (dynamic client registration). redirect_uris holds 1 to 10 exact URLs: https, or http only on a loopback address. The client_id you get back is valid for 365 days.

Register

curl -X POST https://api.flipbird.io/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "Example CRM", "redirect_uris": ["https://crm.example.com/flipbird/callback"]}'

2. Send the person's browser to the authorization endpoint. scope is space-separated scopes, code_challenge the base64url SHA-256 of your verifier, and resource exactly https://api.flipbird.io/api/v1. The request is valid for 10 minutes.

Authorize

https://api.flipbird.io/oauth/authorize?response_type=code
  &client_id=ocl_…
  &redirect_uri=https%3A%2F%2Fcrm.example.com%2Fflipbird%2Fcallback
  &scope=documents.read%20documents.publish
  &state=…
  &code_challenge=…
  &code_challenge_method=S256
  &resource=https%3A%2F%2Fapi.flipbird.io%2Fapi%2Fv1

3. Your redirect URI receives code and state (or error=access_denied if they decline). Exchange the code within 5 minutes, as a form post:

A request the authorization endpoint will not start (a wrong response_type, resource, scope or PKCE parameter, or a state over 512 characters) is not sent back to your redirect URI. The person sees an error page naming the OAuth error code, and your callback hears nothing, so check these parameters before sending anyone.

Token

curl -X POST https://api.flipbird.io/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=ocl_… \
  -d code=… \
  -d redirect_uri=https://crm.example.com/flipbird/callback \
  -d code_verifier=… \
  -d resource=https://api.flipbird.io/api/v1
  • The access token, xbo_…, lasts 1 hour. Send it as a bearer token, like a key.
  • The refresh token gets a new access token with grant_type=refresh_token, client_id, refresh_token and resource, and may ask for fewer scopes with scope. Each refresh returns a new refresh token; using an old one again revokes the whole grant.
  • A grant lasts 30 days from approval. After that the person approves again.
  • Revoke a token by posting token and client_id to the revocation endpoint. A refresh token revokes the whole grant.
  • If the approving member is deactivated or leaves, calls answer 403 oauth_owner_deactivated or oauth_owner_removed.

Scopes

A scope lets a credential call a set of endpoints. Each endpoint in the reference lists the scopes it needs, and a call without them answers 403 forbidden with the missing ones in details.missing. A credential holds a scope only while its member's role does: the roles column says which do.

ScopeWhat it allowsRolesIn the API
documents.readRead the documents, folders, versions, publications, exports, fonts, images and analytics the member may see, and download them.Standard, Admin, OwnerRequired by 45 endpoints.
documents.editMake documents, upload versions, edit drafts and change the documents the member may edit: their own, and any they hold an edit grant on.Standard, Admin, OwnerRequired by 35 endpoints.
documents.edit.anyChange any document nobody has restricted, letterheads, and the workspace's shared libraries: images and saved flipbook looks.Admin, OwnerRequired by 7 endpoints.
documents.access.manageRestrict folders and documents nobody has restricted yet, and grant people or groups access to them.Admin, OwnerLets grants.put and grants.delete change access on folders and documents nobody has restricted yet.
documents.trashMove documents and versions the member may edit to the trash, and take them out again.Admin, OwnerRequired by 5 endpoints.
documents.deleteDelete documents and versions for good from the trash. It cannot be undone.OwnerNot used by the API.
documents.publishPublish, schedule and take down the documents the member may edit, set their lead forms and enrichment, and read the leads they collect.Standard, Admin, OwnerRequired by 15 endpoints.
documents.publish.managePublish across the workspace: collections, custom hostnames, deleting a reader's submission, and webhooks that receive lead forms.Admin, OwnerRequired by 7 endpoints.
documents.encryption.manageChoose whether new versions of a document are stored encrypted.OwnerNot used by the API.
links.readRead short links, QR codes, QR designs, where QR codes are placed, and link analytics.Standard, Admin, OwnerRequired by 12 endpoints.
links.editMake short links and QR codes, and change the ones the member made.Standard, Admin, OwnerRequired by 9 endpoints.
links.manageChange any link or QR code in the workspace, and the saved QR designs.Admin, OwnerRequired by 3 endpoints.
tenant.deleteDelete the whole workspace.OwnerNot used by the API.
team.manageInvite, remove and change the role of members, and manage groups.Admin, OwnerRequired by 13 endpoints.
settings.manageChange workspace settings, fonts and webhook endpoints, and find or erase a reader's lead submissions.Admin, OwnerRequired by 11 endpoints.
sso.manageSet up and require single sign-on.OwnerNot used by the API.
billing.readRead the plan, subscription, invoices, payment methods, credits and usage.Owner, AccountsRequired by 7 endpoints.
billing.manageChange the plan, buy credits and change payment details.Owner, AccountsNot used by the API.
keys.manageMake, rotate and revoke API keys.Admin, OwnerNot used by the API.
audit.readRead and export the workspace's audit log.Admin, OwnerRequired by 2 endpoints.

What a credential can reach

Folders and documents can be restricted to the people and groups given access to them. A credential sees and changes exactly what its member could: a document they may not see answers 404 not_found, as if it were not there, and one they may see but not change answers 403 forbidden.

A Standard member changes only the documents they made and those they hold an edit grant on; an Admin changes any document nobody has restricted. The Owner always has access.

Plan features

Some endpoints need a feature of the workspace's plan. Without it they answer 402 plan_required, with the feature and the least plan that has it in details. GET /plan says what the workspace's plan allows.

Credits

Some work is metered in credits, from the plan's monthly allowance and any bought. A workspace never stops serving its flipbooks when credits run out, but once its balance passes the throttle mark, metered work is paused: these endpoints answer 402 credits_required until credits are added. The credits.low webhook says when the balance crosses each mark.

WorkCostsEndpoints
qr_batch5 credits per 100 QR codes, or part of 100.Make links or QR codes from CSV
heavy_renderBy the document's size: 5 up to 10 MiB, 10 up to 50 MiB, 15 up to 100 MiB, 20 up to 250 MiB, 25 above 250 MiB.Export a version as SVG, pictures, an HTML page or an offline flipbook
ocr1 credit per page recognised.Recognise text on a version and store a searchable PDF