Update Embed Configuration

Update an existing embed configuration to modify access settings, permissions, and datamart associations.

Modify existing embed configurations to update access settings, change permissions, or associate with different datamarts. This allows you to evolve your embedded analytics without recreating configurations.

Endpoint Migration Notice: We’re transitioning to kebab-case endpoints. The new endpoint is /api/v2/data-app/embeds. The old endpoint /api/v2/dataApp/embeds will be deprecated soon. Please update your integrations to use the new endpoint format.

Updates to embed configurations take effect immediately for all active embedded dashboards and metrics using this configuration.

Endpoint Formats

New Endpoint (Recommended)

PUT https://api.usedatabrain.com/api/v2/data-app/embeds

Use this endpoint for all new integrations. This is the recommended endpoint format.

Authentication

All API requests must include your API key in the Authorization header. Get your API token when creating a data app - see our data app creation guide for details.

Finding your API token: For detailed instructions, see the API Token guide.

Headers

Authorization · string · required

Bearer token for API authentication. Use your API key from the data app.

Authorization: Bearer dbn_live_abc123...

Content-Type · string · required

Must be set to application/json for all requests.

Content-Type: application/json

Request Body

embedId · string · required

The unique identifier of the embed configuration to update. Get this from the create embed response or list embeds API.

Show Finding embed IDs

• Use the List All Embeds API to get embed IDs
• Check the response from embed creation
• Available in the DataBrain dashboard when viewing embed configurations

accessSettings · object · required

Updated access control settings for the embedded view. Only provided fields will be updated.

accessSettings.datamartName · string

Change the datamart used by this embed configuration.

accessSettings.isAllowEmailReports · boolean

Update email reports permission.

accessSettings.isAllowManageMetrics · boolean

Update metrics management permission.

accessSettings.isAllowMetricCreation · boolean

Update metric creation permission.

accessSettings.isAllowMetricDeletion · boolean

Update metric deletion permission.

accessSettings.isAllowMetricLayoutChange · boolean

Update metric layout change permission.

accessSettings.isAllowMetricUpdate · boolean

Update metric modification permission.

accessSettings.isAllowUnderlyingData · boolean

Update underlying data access permission.

accessSettings.isAllowCreateDashboardView · boolean

Update dashboard view creation permission.

accessSettings.metricCreationMode · 'DRAG_DROP' | 'CHAT'

Update the metric creation mode.

accessSettings.tableTenancySettings · array

Update multi-tenant table access configuration.

accessSettings.tableTenancySettings.name · string

Table name for tenancy configuration.

accessSettings.tableTenancySettings.clientColumn · string

Column name for client-level filtering.

Response

id · string

The ID of the updated embed configuration.

error · null | object

Error object if the request failed, otherwise null for successful requests.

Examples

Error Codes

EMBED_NOT_FOUND · string

Embed configuration not found - The specified embed ID doesn’t exist in the workspace

INVALID_WORKSPACE_NAME · string

Workspace not found - The specified workspace doesn’t exist or you don’t have access

INVALID_DATAMART · string

Invalid datamart - The specified datamart doesn’t exist in the workspace

INSUFFICIENT_PERMISSIONS · string

Insufficient permissions - You don’t have permission to update this embed configuration

AUTHENTICATION_ERR · string

Invalid API key - Check your API key in dashboard settings

HTTP Status Code Summary

Status Code	Description
200	OK - Embed configuration updated successfully
400	Bad Request - Invalid request parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions to update
404	Not Found - Embed configuration not found
409	Conflict - Update conflicts with existing configuration
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Server error occurred

Possible Errors

Error Code	HTTP Status	Description
EMBED_NOT_FOUND	404	Embed configuration not found
INVALID_WORKSPACE_NAME	404	Workspace not found
INVALID_DATAMART	404	Datamart not found
INSUFFICIENT_PERMISSIONS	403	No permission to update
AUTHENTICATION_ERR	401	Invalid API key
INVALID_ACCESS_SETTINGS	400	Invalid access settings
CONFLICTING_UPDATE	409	Update conflicts with existing config
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_SERVER_ERROR	500	Server error

Update Strategies

1. Permission escalation

   Gradually increase permissions based on user needs:

   // Enable metric creation for power users
   await updateEmbed({
     embedId: 'embed_123',
     accessSettings: {
       isAllowMetricCreation: true,
       metricCreationMode: 'CHAT'
     }
   });
   

2. Datamart migration

   Move embed to a different datamart:

   await updateEmbed({
     embedId: 'embed_123',
     accessSettings: {
       datamartName: 'new-datamart'
     }
   });
   

3. Security tightening

   Reduce permissions when needed:

   await updateEmbed({
     embedId: 'embed_123',
     accessSettings: {
       isAllowMetricDeletion: false,
       isAllowUnderlyingData: false
     }
   });
   

Common Update Scenarios

Enable Advanced Features

// Upgrade basic embed to include AI features
await updateEmbed({
  embedId: 'embed_basic',
  accessSettings: {
    isAllowEmailReports: true,
    metricCreationMode: 'CHAT'
  }
});

Migrate to New Datamart

// Move embed to updated datamart
await updateEmbed({
  embedId: 'embed_old',
  accessSettings: {
    datamartName: 'updated-sales-data',
    tableTenancySettings: [
      {
        name: 'new_customer_table',
        clientColumn: 'tenant_id'
      }
    ]
  }
});

Temporary Permission Reduction

// Temporarily reduce permissions during maintenance
await updateEmbed({
  embedId: 'embed_maintenance',
  accessSettings: {
    isAllowMetricCreation: false,
    isAllowMetricUpdate: false,
    isAllowMetricDeletion: false
  }
});

Best Practices

Change Management

• Document all configuration changes
• Test updates in staging first
• Notify stakeholders of permission changes
• Maintain change history and rollback plans

Security

• Follow principle of least privilege
• Regular permission audits
• Monitor for unauthorized changes
• Validate datamart access before updates

Performance

• Batch multiple updates when possible
• Monitor embed performance after changes
• Test with production data volumes
• Update during low-usage periods

User Experience

• Communicate feature changes to users
• Provide training for new capabilities
• Gradual rollout of new permissions
• Collect feedback on configuration changes

Advanced Configuration

Dynamic Permission Updates

// Update permissions based on user tier
const updatePermissionsForTier = async (embedId, userTier) => {
  const permissions = {
    basic: {
      isAllowMetricCreation: false,
      isAllowUnderlyingData: false
    },
    premium: {
      isAllowMetricCreation: true,
      isAllowUnderlyingData: true,
      metricCreationMode: 'CHAT'
    }
  };
  
  await updateEmbed({
    embedId,
    accessSettings: permissions[userTier]
  });
};

Bulk Updates

// Update multiple embeds with same settings
const bulkUpdateEmbeds = async (embedIds, updates) => {
  const promises = embedIds.map(embedId => 
    updateEmbed({
      embedId,
      accessSettings: updates
    })
  );
  
  const results = await Promise.all(promises);
  return results;
};

Quick Start Guide

1. Find your embed ID

   List your existing embed configurations to find the one you want to update:

   curl --request GET \
     --url https://api.usedatabrain.com/api/v2/data-app/embeds \
     --header 'Authorization: Bearer dbn_live_abc123...'
   

2. Update specific permissions

   Update only the settings you want to change. For example, to enable End User Metric Creation:

   curl --request PUT \
     --url https://api.usedatabrain.com/api/v2/data-app/embeds \
     --header 'Authorization: Bearer dbn_live_abc123...' \
     --header 'Content-Type: application/json' \
     --data '{
       "embedId": "embed_abc123def456",
       "accessSettings": {
         "isAllowMetricCreation": true
       }
     }'
   

3. Migrate to new datamart

   Change the datamart associated with your embed:

   curl --request PUT \
     --url https://api.usedatabrain.com/api/v2/data-app/embeds \
     --header 'Authorization: Bearer dbn_live_abc123...' \
     --header 'Content-Type: application/json' \
     --data '{
       "embedId": "embed_abc123def456",
       "accessSettings": {
         "datamartName": "new-datamart-name"
       }
     }'
   

4. Verify the update

   The API will return the embed ID on success:

   const updateResult = await updateEmbed({
     embedId: 'embed_123',
     accessSettings: { isAllowMetricCreation: true }
   });
   
   console.log('Updated embed ID:', updateResult.id);
   console.log('Success:', !updateResult.error);
   

Next Steps

Delete Embed Config

Remove embed configurations you no longer need

List All Embeds

View all embed configurations in your workspace

Generate Guest Token

Create tokens for your updated embed configurations

How to Embed

Learn the basics of embedding DataBrain