Documentation Index
Fetch the complete documentation index at: https://mintlify.com/metabase/metabase/llms.txt
Use this file to discover all available pages before exploring further.
The Permissions API manages user groups and their access permissions to databases, schemas, tables, and collections. This API includes 9 endpoints.
Permissions overview
Metabase uses a group-based permissions system:
- Groups contain users and have permissions
- Permissions graphs define what each group can access
- Database permissions control access to databases and their data
- Collection permissions control access to dashboards and questions
Get permissions graph
Get the complete permissions graph showing all group permissions.
GET /api/permissions/graph
curl -X GET \
https://your-metabase.com/api/permissions/graph \
-H 'X-Metabase-Session: SESSION_TOKEN'
Requires admin permissions.
Response
Map of group IDs to their permissions
Current revision number (for optimistic locking)
{
"revision": 5,
"groups": {
"1": {
"1": {
"data": {
"schemas": "all",
"native": "write"
}
}
}
}
}
Update permissions graph
Update permissions for groups.
PUT /api/permissions/graph
curl -X PUT \
https://your-metabase.com/api/permissions/graph \
-H 'Content-Type: application/json' \
-H 'X-Metabase-Session: SESSION_TOKEN' \
-d '{
"revision": 5,
"groups": {
"1": {
"1": {
"data": {
"schemas": "all",
"native": "write"
}
}
}
}
}'
Request body
Updated permissions graphPermission levels:
"all" - Full access"none" - No access"write" - Read and write"read" - Read only- Schemas can be individually specified
Current revision number (for preventing conflicts)
Updating permissions can affect many users. Changes take effect immediately.
Get database permissions
Get permissions for a specific database.
GET /api/permissions/graph/db/{db-id}
curl -X GET \
https://your-metabase.com/api/permissions/graph/db/1 \
-H 'X-Metabase-Session: SESSION_TOKEN'
Parameters
Get group permissions
Get all permissions for a specific group.
GET /api/permissions/graph/group/{group-id}
curl -X GET \
https://your-metabase.com/api/permissions/graph/group/1 \
-H 'X-Metabase-Session: SESSION_TOKEN'
Parameters
List groups
Get all permission groups.
GET /api/permissions/group
curl -X GET \
https://your-metabase.com/api/permissions/group \
-H 'X-Metabase-Session: SESSION_TOKEN'
Response
[
{
"id": 1,
"name": "All Users",
"member_count": 25
},
{
"id": 2,
"name": "Administrators",
"member_count": 3
}
]
Create group
Create a new permission group.
POST /api/permissions/group
curl -X POST \
https://your-metabase.com/api/permissions/group \
-H 'Content-Type: application/json' \
-H 'X-Metabase-Session: SESSION_TOKEN' \
-d '{
"name": "Analytics Team"
}'
Request body
Group name (minimum 1 character)
Get group
Get details about a specific group.
GET /api/permissions/group/{id}
curl -X GET \
https://your-metabase.com/api/permissions/group/1 \
-H 'X-Metabase-Session: SESSION_TOKEN'
Parameters
Update group
Update a group’s name or properties.
PUT /api/permissions/group/{group-id}
curl -X PUT \
https://your-metabase.com/api/permissions/group/1 \
-H 'Content-Type: application/json' \
-H 'X-Metabase-Session: SESSION_TOKEN' \
-d '{
"name": "Updated Group Name"
}'
Request body
Delete group
Delete a permission group.
DELETE /api/permissions/group/{group-id}
curl -X DELETE \
https://your-metabase.com/api/permissions/group/1 \
-H 'X-Metabase-Session: SESSION_TOKEN'
Cannot delete the “All Users” or “Administrators” default groups.
Group membership
List memberships
Get all group memberships.
GET /api/permissions/membership
curl -X GET \
https://your-metabase.com/api/permissions/membership \
-H 'X-Metabase-Session: SESSION_TOKEN'
Add member to group
Add a user to a permission group.
POST /api/permissions/membership
curl -X POST \
https://your-metabase.com/api/permissions/membership \
-H 'Content-Type: application/json' \
-H 'X-Metabase-Session: SESSION_TOKEN' \
-d '{
"group_id": 1,
"user_id": 5
}'
Request body
User ID to add to the group
Remove member from group
Remove a user from a group.
DELETE /api/permissions/membership/{id}
curl -X DELETE \
https://your-metabase.com/api/permissions/membership/123 \
-H 'X-Metabase-Session: SESSION_TOKEN'
Parameters
Update membership
Update a group membership.
PUT /api/permissions/membership/{id}
curl -X PUT \
https://your-metabase.com/api/permissions/membership/123 \
-H 'Content-Type: application/json' \
-H 'X-Metabase-Session: SESSION_TOKEN' \
-d '{
"is_group_manager": true
}'
Clear group membership
Remove all members from a group.
PUT /api/permissions/membership/{group-id}/clear
curl -X PUT \
https://your-metabase.com/api/permissions/membership/1/clear \
-H 'X-Metabase-Session: SESSION_TOKEN'
This removes all users from the group. Use with caution.
Permission levels
Database permissions
No access to the database
Full access to all schemas and tables
Granular schema-level permissions
Native query permissions
Cannot write native queries
Can write and execute native queries
Collection permissions
No access to the collection
Can view items in the collection
Can create, edit, and delete items
Best practices
Permission management tips:
- Use groups to organize users by role or department
- Grant the minimum permissions needed
- Regularly audit group memberships
- Use the “All Users” group for instance-wide permissions
- Test permissions changes with a non-admin account
Error codes
Invalid permission configuration
Must be an admin to manage permissions
Permission graph revision conflict