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.
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 .
Bearer token for API authentication. Use your API key from the data app. Authorization: Bearer dbn_live_abc123...
Must be set to application/json for all requests. Content-Type: application/json
Request Body
The unique identifier of the embed configuration to update. Get this from the create embed response or list embeds API.
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
Updated access control settings for the embedded view. Only provided fields will be updated. accessSettings.datamartName
Change the datamart used by this embed configuration.
accessSettings.isAllowEmailReports
Update email reports permission.
accessSettings.isAllowManageMetrics
Update metrics management permission.
accessSettings.isAllowMetricCreation
Update metric creation permission.
accessSettings.isAllowMetricDeletion
Update metric deletion permission.
accessSettings.isAllowMetricLayoutChange
Update metric layout change permission.
accessSettings.isAllowMetricUpdate
Update metric modification permission.
accessSettings.isAllowUnderlyingData
Update underlying data access permission.
accessSettings.isAllowCreateDashboardView
Update dashboard view creation permission.
accessSettings.metricCreationMode
Update the metric creation mode.
accessSettings.tableTenancySettings
Update multi-tenant table access configuration. accessSettings.tableTenancySettings.name
Table name for tenancy configuration.
accessSettings.tableTenancySettings.clientColumn
Column name for client-level filtering.
Response
The ID of the updated embed configuration.
Error object if the request failed, otherwise null for successful requests.
Examples
Error Codes
Embed configuration not found - The specified embed ID doesn’t exist in the workspace
Workspace not found - The specified workspace doesn’t exist or you don’t have access
Invalid datamart - The specified datamart doesn’t exist in the workspace
Insufficient permissions - You don’t have permission to update this embed configuration
Invalid API key - Check your API key in dashboard settings
HTTP Status Code Summary
Status Code Description 200OK - Embed configuration updated successfully400Bad Request - Invalid request parameters401Unauthorized - Invalid or missing API key403Forbidden - Insufficient permissions to update404Not Found - Embed configuration not found409Conflict - Update conflicts with existing configuration429Too Many Requests - Rate limit exceeded500Internal Server Error - Server error occurred
Possible Errors
Error Code HTTP Status Description EMBED_NOT_FOUND404 Embed configuration not found INVALID_WORKSPACE_NAME404 Workspace not found INVALID_DATAMART404 Datamart not found INSUFFICIENT_PERMISSIONS403 No permission to update AUTHENTICATION_ERR401 Invalid API key INVALID_ACCESS_SETTINGS400 Invalid access settings CONFLICTING_UPDATE409 Update conflicts with existing config RATE_LIMIT_EXCEEDED429 Too many requests INTERNAL_SERVER_ERROR500 Server error
Update Strategies
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'
}
});
Datamart migration
Move embed to a different datamart: await updateEmbed ({
embedId: 'embed_123' ,
accessSettings: {
datamartName: 'new-datamart'
}
});
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
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...'
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
}
}'
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"
}
}'
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