AzuraCast API Key required permissions

Introduction

In AzzyBot 2.0 you can use up to two API keys per station. Why is this necessary, you may ask? The answer is simple!

By having a separate API key for general administrative tasks and station-related tasks, we can tailor the permissions to each use case, ensuring the bot only ever uses the minimal permissions required for each task.

Important

I strongly recommend creating a dedicated user and role just for the bot! This allows you to monitor what the bot does in the Audit Log, an important step for the security of your instance.

The Admin API Key

The first API key is used to manage general administrative aspects of your instance and stations, such as:

• Retrieving useful information about your station to work with inside the commands:
  • Is it actively playing music?
  • Is AutoCue enabled?
  • Is HLS streaming enabled?
  • Is the option to write playlists back to Liquidsoap active?
  • Are users allowed to request songs?
  • Does it have a custom song request threshold that should be respected?
• Retrieving hardware stats from your instance
• Starting and stopping the station
• Updating your instance
• Viewing system logs to present them to you

To work without issues, the user associated with the admin API key should have the following global permissions inside AzuraCast:

Permissions

• All Permissions (only for update checks, as this is hidden)
• View Administration Page
• View System Logs
• Administer Stations

Note

If you choose to grant the bot the "All Permissions" permission, it will only need that one. However, you should only do this if you want the bot to notify you about updates.

The Station API Key

The second API key (preferably used for tasks involving stations) is the station API key. Its general use cases include:

• Checking if a song has been played recently
• Deleting song requests
• Retrieving information about requested songs
• Retrieving the current song queue
• Retrieving music files to populate a JSON file cache and determine if files have changed
• Retrieving playlists
• Retrieving songs available for request
• Retrieving the station status
• Skipping a song

To work without issues, the station API key should have the following permissions:

Permissions

• View Station Page
• View Station Reports
• Manage Station Broadcasting
• Manage Station Media

API Endpoints Used

For an overview of the API endpoints the bot accesses, see below:

API Endpoints

Administrative Endpoints

• /api/admin/logs
• /api/admin/log/id
• /api/admin/server/stats
• /api/admin/status
• /api/admin/stations
• /api/admin/station/id
• /api/admin/updates

Station Endpoints

• /api/station/id/history
• /api/station/id/playlists
• /api/station/id/playlist/id
• /api/station/id/queue
• /api/station/id/status
• /api/station/id/reports/requests
• /api/station/id/files