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_deactivateduntil they are reactivated. If they leave the workspace, it answers 403key_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.
| Endpoint | URL |
|---|---|
| Authorization server metadata | https://api.flipbird.io/.well-known/oauth-authorization-server |
| Protected resource metadata | https://api.flipbird.io/.well-known/oauth-protected-resource/api/v1 |
| Client registration | https://api.flipbird.io/oauth/register |
| Authorization | https://api.flipbird.io/oauth/authorize |
| Token | https://api.flipbird.io/oauth/token |
| Revocation | https://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_tokenandresource, and may ask for fewer scopes withscope. 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
tokenandclient_idto the revocation endpoint. A refresh token revokes the whole grant. - If the approving member is deactivated or leaves, calls answer 403
oauth_owner_deactivatedoroauth_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.
| Scope | What it allows | Roles | In the API |
|---|---|---|---|
documents.read | Read the documents, folders, versions, publications, exports, fonts, images and analytics the member may see, and download them. | Standard, Admin, Owner | Required by 45 endpoints. |
documents.edit | Make 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, Owner | Required by 35 endpoints. |
documents.edit.any | Change any document nobody has restricted, letterheads, and the workspace's shared libraries: images and saved flipbook looks. | Admin, Owner | Required by 7 endpoints. |
documents.access.manage | Restrict folders and documents nobody has restricted yet, and grant people or groups access to them. | Admin, Owner | Lets grants.put and grants.delete change access on folders and documents nobody has restricted yet. |
documents.trash | Move documents and versions the member may edit to the trash, and take them out again. | Admin, Owner | Required by 5 endpoints. |
documents.delete | Delete documents and versions for good from the trash. It cannot be undone. | Owner | Not used by the API. |
documents.publish | Publish, schedule and take down the documents the member may edit, set their lead forms and enrichment, and read the leads they collect. | Standard, Admin, Owner | Required by 15 endpoints. |
documents.publish.manage | Publish across the workspace: collections, custom hostnames, deleting a reader's submission, and webhooks that receive lead forms. | Admin, Owner | Required by 7 endpoints. |
documents.encryption.manage | Choose whether new versions of a document are stored encrypted. | Owner | Not used by the API. |
links.read | Read short links, QR codes, QR designs, where QR codes are placed, and link analytics. | Standard, Admin, Owner | Required by 12 endpoints. |
links.edit | Make short links and QR codes, and change the ones the member made. | Standard, Admin, Owner | Required by 9 endpoints. |
links.manage | Change any link or QR code in the workspace, and the saved QR designs. | Admin, Owner | Required by 3 endpoints. |
tenant.delete | Delete the whole workspace. | Owner | Not used by the API. |
team.manage | Invite, remove and change the role of members, and manage groups. | Admin, Owner | Required by 13 endpoints. |
settings.manage | Change workspace settings, fonts and webhook endpoints, and find or erase a reader's lead submissions. | Admin, Owner | Required by 11 endpoints. |
sso.manage | Set up and require single sign-on. | Owner | Not used by the API. |
billing.read | Read the plan, subscription, invoices, payment methods, credits and usage. | Owner, Accounts | Required by 7 endpoints. |
billing.manage | Change the plan, buy credits and change payment details. | Owner, Accounts | Not used by the API. |
keys.manage | Make, rotate and revoke API keys. | Admin, Owner | Not used by the API. |
audit.read | Read and export the workspace's audit log. | Admin, Owner | Required 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.
| Work | Costs | Endpoints |
|---|---|---|
qr_batch | 5 credits per 100 QR codes, or part of 100. | Make links or QR codes from CSV |
heavy_render | By 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 |
ocr | 1 credit per page recognised. | Recognise text on a version and store a searchable PDF |