Configuring your team settings with the Digital Samba Developer API

8 min read
September 13, 2023

Your Digital Samba team is the account-level layer that holds your subdomain, your API credentials, your team members and the default settings every new room inherits. You can manage all of it from the dashboard, and most of it through the REST API as well – which is handy once team configuration becomes part of your deployment workflow rather than a one-off task.

Table of Contents 

  1. How do you get started?
  2. How do you add members to your team?
  3. How do you assign team roles to team members?
  4. How to configure your default room settings
  5. Frequently asked questions

In this guide, we'll walk through setting up a team, authenticating to the Digital Samba REST API, adding members, assigning team roles and configuring your default room settings – with working requests you can copy straight into your terminal.

How do you get started?

A team in Digital Samba is the group of people who build and manage the integration of Digital Samba Embedded into your website or application. That usually means developers, plus anyone else who needs to create rooms, manage recordings or configure settings at an advanced level.

Every team has exactly one owner, and may also have any number of admins and members. Some of the setup happens in the dashboard, and the rest can be done over the API – we'll cover both routes below.

How do you create a team?

You don't create a team as a separate step – it's created automatically the moment you sign up for a Digital Samba account, and you become its owner. During sign-up, you'll be asked to choose a subdomain, which acts as a unique identifier for your team – think of it as your team name.

Set up your team by adding a subdomain - Digital Samba

Digital Samba uses your subdomain to build the branded domain that appears in every link you share with meeting participants. If you choose 'lecture-room' as your subdomain, your rooms will live at https://lecture-room.digitalsamba.com/room. As the team owner, you can edit the subdomain later from the Team section of the dashboard – just remember that any room links you've already shared will stop working.

How to authenticate REST API requests

Every request to the Digital Samba REST API is authenticated with two values: your team ID and your developer key. Both are generated at sign-up, and you can find them at any time in the Team section of your dashboard.

Developer key and team ID in the Team section - Digital Samba

The API accepts both HTTP Basic authentication and a Bearer token. In both cases, the credential is your team ID and developer key joined with a colon and Base64-encoded:

Authorization: Bearer base64(teamId:developerKey)
Authorization: Basic base64(teamId:developerKey)

The simplest way to try it is with cURL, which handles the encoding for you when you pass --user. To see your team settings in action, create a room by sending a POST request to the /rooms endpoint. The only required field is privacy, which accepts 'public' or 'private' – if you skip friendly_url, the API generates one for you:

curl --request POST \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1/rooms \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{"privacy": "public", "friendly_url": "my-standup"}'

The new room inherits your team's default room settings – we'll come to those shortly. Your team also ships with three preset room roles (moderator, speaker and attendee); if you add more than one role to a room, you must also set a default_role. You can read more in our guide to managing participants and roles in a video call.

IMPORTANT: Never expose your developer key in front-end code or share it with external sources. Treat it like a password. The key never expires, but if you suspect it has leaked, you can regenerate it at any time by clicking the regenerate icon next to the developer key field in the Team section – you'll then need to authenticate with the new key.

How do you add members to your team?

To add team members, open the 'Team' section of the dashboard and click the 'Add members' button. Team owners and team admins can both do this.

Add members button - Digital Samba

The dashboard generates an invite link for you to copy and send to your future team members. The link points to the Digital Samba sign-up page, where invitees are signed up as plain team members – you can promote them afterwards if they need more access.

While you wait for everyone to join, you don't need to create a room from scratch to experiment: your account comes with a demo room, so you can try out your team settings right away.

Demo room - Digital Samba

How do you assign team roles to team members?

Each person appears in the 'Team members' section with their email address, role and joining date. The team owner role is assigned automatically to whoever created the team.

The Team members section - Digital Samba

Team roles and permissions

Digital Samba offers three team roles: owner, admin and member. 

  1. The team owner is created automatically when a new team is formed, and there can only be one per team. The owner's profile is linked to billing, which makes them responsible for managing the account, keeping billing information up to date and handling product upgrades. The owner cannot be removed by team admins. Ownership can't be transferred from the dashboard – if you need to hand over a team, contact support.
  2. Team admins have the same access level as the owner, except they cannot manage billing or remove the team owner. They can add and remove team members, assign team roles and configure room defaults.
  3. Team members can do everything else – create rooms, configure roles, set up webhooks, manage recordings, troubleshoot sessions and view usage statistics – but they cannot add or remove team members, assign team roles or change the room defaults.

A team can have an unlimited number of admins and members, but only one owner. You'll find the full breakdown in our documentation.

Team roles are not the same as room roles, and the distinction matters. Team roles control what someone can do in the dashboard and over the API, while room roles – moderator, speaker, attendee and any custom roles you define – control what participants can do inside a video call.

You can also control which team roles may open recordings and download transcripts and files. The team owner always has access, while access for admins and members is customisable – useful when recordings contain material that not everyone on the team should see.

How do you promote, demote or remove team members?

To change someone's team role, click the three-dot icon next to their entry in the Team section. 

Promote, demote or remove team members - Digital Samba

From there, you can promote a team member to admin with 'Promote', demote an admin back to member with 'Demote', or take someone off the team entirely with 'Remove'. That's all there is to managing your team's structure day to day.

How to configure your default room settings

Default room settings are the template every new room starts from. Configure them once, and each room you create – over the API or in the dashboard – inherits your branding, language and feature choices, which keeps the experience consistent without repeating the same configuration for every room.

The inheritance rule is precise: new rooms inherit the defaults, and existing rooms inherit them too, but any setting you've customised on a specific room is never overridden. If you set a room's primary colour to red and later change the default to blue, that room stays red.

You can edit the defaults in the dashboard – the 'Default room settings' button lives in the Rooms section, as covered in our guide to configuring room defaults using the dashboard – or over the API, as below.

How to view your current default room properties

Before changing anything, it helps to see what's currently set. Send a GET request against the root endpoint:

curl --request GET \
  --url https://api.digitalsamba.com/api/v1 \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY

The response lists your team's current default room properties. Here's a trimmed example showing the kind of fields you'll get back – branding colours, toolbar position, UI language and feature toggles, along with your usage for the current period:

{
    "id": "c4fa4435-1381-4fd4-8bef-38a25da7eee1",
    "domain": "myTeamNameHere",
    "topbar_enabled": true,
    "toolbar_enabled": true,
    "toolbar_position": "bottom",
    "toolbar_color": "#000000",
    "primary_color": "#3771E0",
    "background_color": "#000000",
    "palette_mode": "light",
    "language": "en",
    "audio_on_join_enabled": true,
    "video_on_join_enabled": true,
    "screenshare_enabled": true,
    "participants_list_enabled": true,
    "chat_enabled": true,
    "e2ee_enabled": false,
    "join_screen_enabled": true,
    "logo_enabled": false,
    "recordings_enabled": true,
    "virtual_backgrounds_enabled": true,
    "raise_hand_enabled": true,
    "used_participation_minutes": 570
}

How to configure your default room settings with the Digital Samba Developer API

To change the defaults, send a PATCH request against the same root endpoint, passing only the fields you want to change.

Suppose you want a uniform brand identity across your video conferences: the toolbar on the right in your brand's blue, a light-blue primary colour on a white background, chat enabled, your logo displayed and English as the UI language. That looks like this:

curl --request PATCH \
  --header "Content-Type: application/json" \
  --url https://api.digitalsamba.com/api/v1 \
  --user YOUR_TEAM_ID:YOUR_DEVELOPER_KEY \
  --data '{
    "toolbar_position": "right",
    "toolbar_color": "#0000FF",
    "primary_color": "#ADD8E6",
    "background_color": "#FFFFFF",
    "language": "en",
    "chat_enabled": true,
    "logo_enabled": true
  }'

You can update as many fields in one request as you wish, and the response confirms the update. If you ever want a clean slate, the dashboard's 'Reset to factory settings' button restores the original defaults. See our documentation for the full list of configurable fields.

With your team set up and your defaults matching your brand, every room you create is ready for participants the moment it exists – and because it's all available over the API, you can fold team configuration into your own provisioning flow. If you want your backend to react to what happens in those rooms, the next step is wiring up webhooks.

Get started today with a free account and 10,000 participation minutes per month of HD-quality video calls. 

Frequently asked questions

Where do I find my developer key and team ID?

Both are in the Team section of your Digital Samba dashboard, generated when you sign up. You use them together to authenticate every REST API request, either as a Basic credential or a Bearer token.

What should I do if my developer key leaks?

Regenerate it from the Team section of the dashboard by clicking the regenerate icon next to the developer key field. The old key stops working immediately, so update your integration to authenticate with the new one.

Can I change my team subdomain after signing up?

Yes. As the team owner, you can edit the subdomain in the Team section of the dashboard. Keep in mind that your room links include the subdomain, so links you shared before the change will no longer work.

How many owners, admins and members can a team have?

A team always has exactly one owner, and can have an unlimited number of admins and members. Ownership can't be changed from the dashboard – contact Digital Samba support if you need to transfer it.

What's the difference between team roles and room roles?

Team roles (owner, admin, member) control what someone can do in the dashboard and over the API. Room roles (moderator, speaker, attendee and custom roles) control what participants can do inside a video call, such as sharing a screen or muting others.

Will changing default room settings affect my existing rooms?

Existing rooms inherit the new defaults, but any setting you customised on a specific room is never overridden. Only values a room still inherits will follow the updated defaults.

Request a free consultation with our dev team
Add customisable video calls to your website or application with the Digital Samba API
Get a consultation