Scopes & Permissions

Scopes control what actions your API key can perform. Request only the scopes your application needs.

What are Scopes?

Scopes are permissions that determine which API endpoints your API key can access. When creating an API key, you select which scopes to grant. This follows the principle of least privilege - only grant the permissions your application needs.

Available Scopes

Scope Combinations

You can request multiple scopes for a single API key. Here are common combinations:

Managing Scopes

Creating API Keys with Scopes

1. Sign in to bassode.com
2. Go to Account → API Keys
3. Click "Create New API Key"
4. Give your key a descriptive name
5. Select the scopes you need (checkboxes)
6. Click "Create" and save your credentials

Updating Scopes

You can modify the scopes of an existing API key:

1. Go to Account → API Keys
2. Find the API key you want to modify
3. Click "Edit" or "Manage Scopes"
4. Check or uncheck scopes as needed
5. Save changes

Scope Verification

When you make a request, the API checks if your API key has the required scope. If not, you'll receive a 403 Forbidden response:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "Insufficient permissions",
  "message": "Your API key does not have the required scope: speakers:read",
  "requiredScope": "speakers:read",
  "yourScopes": ["amplifiers:read", "dacs:read"]
}

Best Practices

• Request minimum necessary scopes - Only request scopes your application actually uses
• Use separate keys for different applications - Create different API keys with different scopes for different use cases
• Review scopes regularly - Audit your API keys and remove scopes you no longer need
• Document required scopes - Clearly document which scopes your application requires in user-facing documentation
• Handle permission errors gracefully - Show helpful error messages when scope permissions are insufficient

Scope Naming Convention

Scopes follow the pattern: resource:action

• Resource: The type of data (speakers, amplifiers, dacs, etc.)
• Action: What you can do (read, write, delete, etc.)

Currently, all available scopes are read scopes. Future versions may introduce write and delete scopes for managing equipment data.

Checking Your Scopes

You can view the scopes assigned to your API keys in the API Keys dashboard. Each key shows:

• Key name and identifier
• Assigned scopes (with badges)
• Creation date
• Last used timestamp
• Usage statistics

Example: Handling Scope Errors

async function fetchSpeakers() {
  try {
    const response = await fetch('https://api.bassode.com/api/speakers', {
      headers: {
        'X-Api-Key': API_KEY,
        'X-Api-Secret': API_SECRET
      }
    });

    if (response.status === 403) {
      const error = await response.json();
      console.error(`Missing scope: ${error.requiredScope}`);
      console.error(`Your scopes: ${error.yourScopes.join(', ')}`);
      
      // Show user-friendly message
      alert('Your API key does not have permission to access speakers. ' +
            'Please update your API key scopes in your account settings.');
      return null;
    }

    response.ensureSuccessStatusCode();
    return await response.json();
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

Future Scopes

We're planning to introduce additional scopes in future releases:

• speakers:write - Create and update speaker data
• amplifiers:write - Create and update amplifier data
• favorites:read / favorites:write - Manage user favorites
• comparisons:read / comparisons:write - Manage equipment comparisons
• analytics:read - Access usage analytics and insights

Stay tuned to our changelog for updates on new scopes and features!

Next Steps