Skip to content
Foliosodev
Sign in Get started
Menu
On this page

Your account

API tokens

Create personal API tokens to use the Folioso REST API from scripts and integrations. Each token acts as you, in one organisation, with read-only or read-and-write access.

Who can create tokens

  • The REST API is available if your organisation's plan includes API access. If it doesn't, the section says The REST API is available on the Pro plan and above. See the pricing page.
  • Any member of the organisation can create tokens. You don't need to be an admin.
  • A token can never do more than you can. If you're a viewer in a space, your token can read it but not change it. If you lose access to a space or page, so does your token.

One organisation per token

A token is bound to the organisation you created it in, and works only at that organisation's address. A leaked token reaches nothing else. If you belong to several organisations, create a token in each one you want to automate.

The API tokens section shows the organisation's name and the exact base address to send requests to, for example https://acme.folioso.dev/api/v1. It lists only the tokens you created in this organisation.

Create a token

  1. Open Settings while you're in the organisation, and go to API tokens.
  2. Enter a Token name (up to 60 characters) so you can recognise it later, for example Deploy script.
  3. Under Access, choose Read only or Read and write.
  4. Under Expires, choose Never, In 30 days, In 90 days or In a year.
  5. Select Create token.
  6. Copy the token from the panel that appears and store it somewhere safe.

Important

The token is shown only once. Folioso keeps only a fingerprint of it and can't show it again. If you lose it, revoke it and create a new one.

Access levels

Access Can do
Read only List spaces, groups, tags and pages, search, and read pages.
Read and write Everything a read-only token can, plus create, update and delete pages (deleting moves a page to the recycle bin).

See the API overview for the full list of endpoints.

Use a token

Send the token in the Authorization header of every request:

bash
curl https://acme.folioso.dev/api/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: application/json"

See Authentication and limits.

Track and revoke tokens

Each token in the list shows its access (Read/write or Read only), when it was last used (or Never used), when it was created and, if it has one, when it expires. Expired tokens are marked Expired and stop working.

To revoke a token, select Revoke next to it. It stops working immediately.

You can always revoke tokens, even if your organisation has moved to a plan without API access.

When a token stops working

A token is refused when:

  • it has expired or been revoked;
  • your organisation's plan no longer includes API access;
  • you're no longer a member of the organisation, or your membership is suspended (your tokens work again if the suspension is lifted);
  • your account must use two-factor authentication and you haven't set it up yet.