Set up BookStack
Prerequisites
You must have Administrator access to your BookStack instance.
BookStack version 0.31 or above (API support was introduced in 0.31).
Create a service account role
The service account needs a dedicated role with the minimum permissions required for Amber to index content.
Log in to your BookStack instance as an Administrator. Go to Settings via the top right menu.
Click on Settings in the top navigation bar
Go to Settings → Roles.
In the Settings submenu, click on Roles
Click Create New Role.
On the User Roles page, click Create New Role
Fill out the form with the following details:
Enter the Role Name and Short Description as shown
Under System Permissions, enable:
Access System API - required for any API token usage
Manage System Settings & Permissions - required for Amber to read per-book permission data
Under Asset Permissions, set View access to all shelves, books, chapters, and pages you want Amber to index.
Enable View access for Shelves, Books, Chapters and Pages
⚠️ Do not grant edit, delete, or admin permissions. Read-only access is sufficient.
Click Save Role to save your changes.
Click Save Role to confirm
Create a service account user
Go to Settings → Users.
In the Settings submenu, click on Users
Click Add New User.
On the Users page, click Add New User
Fill out the form with the following details:
Fill in the user details and assign the AmberConnector role
Click Save to create the user.
Click Save to confirm
Generate an API Token
The service account needs a personal API token to allow Amber programmatic access to BookStack content. The API respects user permissions - only content accessible to this user will be indexed by Amber.
Log in to BookStack as the AmberConnector service account user. Click on the user avatar in the top right corner.
Click the user avatar in the top right corner
Go to My Account from the dropdown menu.
Select My Account from the dropdown
Then navigate to Access & Security.
Click Access & Security in the account sidebar
Click Create Token.
In the API Tokens section, click Create Token
Fill out the token form with the following details:
Fill in the token name and expiry date, then click Save
After saving, the Token ID and Token Secret will be displayed. Copy and securely store both - the secret will only be displayed once and cannot be retrieved afterwards.
Copy the Token ID and Token Secret - store them securely
Share credentials
Once the service account is created and the API token has been generated, please securely share the following information with the Amber support team:
URL of your BookStack instance (e.g.
https://bookstack.yourcompany.com)Token ID of the AmberConnector service account
Token Secret of the AmberConnector service account