API Access

Connect external tools, scripts, and AI agents to your Boardwise account using API tokens.

How It Works

Boardwise uses a device authorization flow to grant API access. This is the same pattern used by services like GitHub CLI and streaming device apps. The process works like this:

1. An external tool (CLI, script, or agent) requests access and displays a short code
2. You sign in to Boardwise in your browser and enter the code
3. You review and approve the request
4. The tool receives a secure API token

This approach keeps your sign-in codes and passkeys private. The external tool never sees your login credentials.

Authorizing a New Device

When an external tool requests access, it will show you an 8-character code (for example, ABCD-1234) and a link to the Boardwise authorization page.

1. Open the authorization page at boardwise.test/authorize (or follow the link the tool provides)
2. Sign in to Boardwise if you are not already logged in
3. Enter the 8-character code shown on your device
4. Review the name of the application requesting access
5. Click Approve to grant access, or Deny to reject the request

After approval, the external tool will automatically receive its API token and can begin accessing your account.

Managing Your Tokens

View and revoke your API tokens from the token management page:

1. Go to My Stuff > API Tokens (or navigate to /my/api_tokens)
2. You will see a list of all your tokens with:
   • Name - The name of the tool that requested access
   • Token hint - The last 4 characters of the token for identification
   • Last used - When the token was last used to make an API request
   • Created - When the token was created
3. Click Revoke to permanently disable a token

Revoking a Token

If you suspect a token has been compromised, or you no longer use a tool:

1. Go to My Stuff > API Tokens
2. Find the token you want to revoke
3. Click Revoke and confirm

Revoked tokens cannot be restored. The external tool will need to request new access through the device authorization flow.

Security

• Tokens provide the same access as your user account, scoped to whichever organization a request targets
• Each token is unique to one tool. Revoking one token does not affect others
• Tokens are stored securely using one-way hashing. Boardwise cannot retrieve the full token after creation
• You can revoke tokens at any time from your token management page

For Developers

If you are building a tool that integrates with the Boardwise API, see the device authorization flow endpoints:

1. POST /api/v1/auth/device - Start the flow by providing a client_name
2. Display the returned user_code and verification_uri to the user
3. Poll POST /api/v1/auth/token at the specified interval, sending grant_type=urn:ietf:params:oauth:grant-type:device_code and the device_code. Keep polling while the answer is authorization_pending.
4. Use the returned access_token as a Bearer token in the Authorization header
5. Verify your token works with GET /api/v1/auth/me

Tool Discovery

Call GET /api/v1/tools with your Bearer token to get a machine-readable list of all available API endpoints, their parameters, and descriptions. This is designed for AI agents and automated tools to discover capabilities dynamically.

Available Endpoints

Resource endpoints use the same URLs as the web application with .json format. Include your Bearer token in the Authorization header.

Endpoint	Method	Description
/api/v1/tools	GET	Discover all available API endpoints
/{slug}/committees.json	GET	List boards and committees
/{slug}/committees/{id}.json	GET	Get committee details with members
/{slug}/board.json	GET	Get board details with members
/{slug}/meetings.json	GET	List meetings (filter: group_id, status)
/{slug}/meetings/{id}.json	GET	Get meeting with agenda, attendees, documents
/{slug}/meetings.json	POST	Create a meeting
/{slug}/meetings/{id}/agenda_items.json	POST	Add an agenda item to a meeting
/{slug}/people.json	GET	List active people in the directory
/{slug}/action_items.json	GET	List action items (filter: group_id, status)
/{slug}/action_items.json	POST	Create an action item
/{slug}/documents.json	GET	List documents (filter: group_id)
/{slug}/board/messages.json	GET	List board messages
/{slug}/committees/{id}/messages.json	GET	List committee messages
/{slug}/messages/{id}.json	GET	Get message with recipients and read status
/{slug}/board/messages.json	POST	Send a message to the board
/{slug}/committees/{id}/messages.json	POST	Send a message to a committee

Authorization

API endpoints use the same permission system as the web application. The authenticated user's organization role and group memberships determine what data they can access. For example, a guest user will only see meetings they have been invited to.

Related Topics

• Account Settings
• Security and Privacy
• Setting Up Passkeys