Scopes & Permissions

Scopes control which API endpoints your API key can access. Request only the scopes your application needs.

What are Scopes?

When you create an API key, you assign it one or more scopes. Each scope unlocks a specific category of endpoints. The API validates the scope on every request — a missing or insufficient scope returns 403 Forbidden.

Available Scopes

auth:login

Allows authenticating Bassode users and retrieving their registered devices.

Grants access to:

  • POST /api/Users/Login — authenticate a user, receive JWT
  • GET /api/Devices — list all Bassode-compatible devices registered by the authenticated user

Use cases:

  • Sign in Bassode users from your application
  • List devices owned by a logged-in user

auth:register

Allows creating new Bassode user accounts.

Grants access to:

  • POST /api/Users/Register — create a new user account

Use cases:

  • User registration flows in third-party applications

register:device

Allows registering a Bassode-compatible device to an authenticated user account. Intended for device firmware and provisioning tools.

Grants access to:

  • POST /api/Devices/Register — register a Bassode-compatible device for the authenticated user (requires JWT)

Use cases:

  • Bassode Transport firmware — links the device to the user's account
  • Hardware provisioning and activation tools

read:devices

Read access to the Bassode audio device catalog (DACs, amplifiers, speakers).

Grants access to:

  • GET /api/Dac — query the audio device catalog
  • GET /api/SubscriptionPlans — list available subscription plans

Use cases:

  • Display audio equipment catalogs
  • Build compatibility checkers and comparison tools
  • Show available subscription plans to users

write:devices

Write access to the audio device catalog. Required for importing or updating catalog data.

Grants access to:

  • POST /api/Dac/import — import catalog data from JSON (Admin JWT also required)

Use cases:

  • Catalog management and data import tooling
Note: This scope also satisfies read:devices — a key with write:devices can also read the catalog.

system:full-access

Internal scope — reserved for the Bassode UI service. Not available to third-party applications.

Grants access to:

  • All API endpoints without restriction
  • User management, admin operations
Note: This scope cannot be assigned through the API Keys dashboard. It is a database-only scope used exclusively by the Bassode web application.

Scope Combinations

Audio Catalog Access

read:devices

Ideal for: applications that display or query the audio device catalog without user accounts.

User Authentication + Catalog

auth:login read:devices

Ideal for: applications that sign in users and also browse the catalog.

Full User Flow

auth:login auth:register read:devices

Ideal for: applications with complete registration, login, and catalog browsing features.

Bridge Device Integration

auth:login register:device

Ideal for: Bridge device firmware and provisioning tools that authenticate users and register the device to their account.

Managing Scopes

Assigning scopes when creating a key

  1. Sign in to bassode.com with an active subscription
  2. Go to Account → API Keys
  3. Click "Create New API Key"
  4. Select the scopes your application needs
  5. Save both the key and secret immediately — the secret is shown only once

Updating scopes on an existing key

  1. Go to Account → API Keys
  2. Find the key you want to modify
  3. Click "Manage Scopes"
  4. Update the scope selection and save
Note: Scope changes take effect immediately on the next request.

Scope Verification Error

If your API key does not have the required scope, the API returns:

HTTP/1.1 403 Forbidden

{
  "error": "Insufficient permissions",
  "message": "Your API key does not have the required scope"
}

Best Practices

Next Steps

Explore Endpoints See Code Examples