Authentication

Broodnet uses three authentication methods, each with a distinct scope and header:

Method	Header	Scope	Used by
Bearer	Authorization: Bearer <token>	User / org	Dashboard (frontend)
Organization API key	x-organization-key: brn_...	Org	Third-party scripts, integrations
Mailbox key	x-mailbox-key: <token>	Single mailbox	CLI, MCP agents

Authentication methods

Bearer (session)

Sign up and sign in with email and password through the Broodnet dashboard. Sessions last 7 days and refresh automatically when active. Social sign-in via Google and GitHub is also available.

Bearer sessions have full access — scope checks do not apply. The user’s organization role is the only permission boundary.

Authorization: Bearer <session-token>

Organization API keys

API keys provide programmatic access to Broodnet resources on behalf of an organization. Use them when integrating Broodnet into your own services, scripts, or agent workflows.

API keys are:

• Organization-scoped — each key is tied to a specific organization and can only access that organization’s resources
• Scope-limited — keys are granted a subset of permissions (scopes) at creation time, restricting what they can do
• Prefixed — all keys start with brn_ for easy identification
• Named — every key requires a descriptive name to help you track what each key is used for

x-organization-key: brn_your_key_here

Mailbox keys

Mailbox keys are used by the CLI and MCP server to authenticate as a specific mailbox. They are issued once when a mailbox is created and grant access only to that mailbox’s resources.

x-mailbox-key: <token>

Scopes

Organization API keys use scopes to control what actions the key can perform. When creating a key, you select which scopes to grant. Available scopes:

Scope	Description
org:read	Read organization details and usage
mailbox:create	Create new mailboxes
mailbox:read	List and view mailboxes
mailbox:write	Update mailbox settings
mailbox:delete	Delete mailboxes

A key can only perform actions covered by its granted scopes. Requests outside those scopes receive a 403 Forbidden response.

Roles and permissions

Every organization member has a role that determines what they can do. Roles apply to both dashboard sessions and API key access — an API key inherits the role of the user who created it.

Role	Mailboxes	Domains	Organization
Owner	Full control	Full control	Full control
Admin	Full control	Full control	Manage members, settings
Member	Read only	Read only	View only

API key access is checked against both the key’s scopes and the creator’s current role. If a user’s role is downgraded after creating a key, the key’s effective permissions are also reduced.

Authorization layers

Requests go through multiple authorization checks in order:

1. Authentication — is the request from a valid session or API key?
2. Scope check — does the API key have the required scope? (bearer sessions bypass this)
3. Role check — does the user’s organization role permit this action?
4. Plan check — does the organization’s plan allow this feature or have remaining quota?

Each layer is independent. A request must pass all applicable checks to proceed.

Scopes vs roles

Scopes and roles are separate authorization mechanisms that serve different purposes:

• Scopes restrict what an API key is allowed to do. They use flat resource:action tokens (e.g. mailbox:create) following standard OAuth conventions. A key can only perform actions covered by its granted scopes. Bearer sessions (dashboard users) bypass scope checks entirely — they have full access by definition.

• Roles restrict what a user is allowed to do based on their membership in the organization. They use Better Auth’s access control system, which models permissions as { resource: [actions] } capability matrices per role (owner, admin, member).

Both checks run independently on every request. An API key must have the right scope and its creator must have a role that permits the action. This means revoking a user’s admin role also effectively restricts all keys they created, even if those keys have broad scopes.