Working with Organizations

1. Creating Organizations

Property	Description	Default Value	Notes
name	Unique name for the organization	None	Required field
id	Unique identifier for the organization	Auto-generated	Read-only after creation
created	Timestamp when organization was created	Auto-generated	Read-only
updated	Timestamp when organization was last updated	Auto-generated	Read-only

Example: Creating an Organization via API

{
  "name": "Acme Corp",
  "id": "acme-corp-id"
}

Note: The organization ID is auto-generated if not provided, but it's recommended to set a custom ID for better tracking and integration.

2. Switching Between Organizations

Method	Description	Notes
UI Navigation	Use the organization switcher in the top-left corner of the Grafana dashboard.	Available to users with appropriate permissions in multiple organizations.
API Endpoint	`GET /api/user/orgs`	Returns a list of organizations the current user belongs to.
API Switch	`POST /api/user/using-org/:orgId`	Switches the current user's active organization to the specified ID.

Example: Switching Organization via API

curl -H "Authorization: Bearer <API_TOKEN>" \
     -X POST "http://localhost:3000/api/user/using-org/2"

Note: The organization ID must be one of those returned by GET /api/user/orgs.

3. Setting Organization Preferences

Preference	Description	Default Value	Notes
theme	UI theme for the organization	`dark`	Options: `light`, `dark`, `auto`
homeDashboard	Default dashboard for organization members	`None`	Path to dashboard JSON or UID
timeZone	Default timezone for organization	`utc`	IANA timezone identifier
dateFormats	Default date formats for the organization	`ISO 8601`	Customizable via API or UI

Example: Setting Theme Preference via API

curl -X PUT "http://localhost:3000/api/org/preferences" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"theme": "light"}'

Note: Organization preferences are inherited by all users in the organization unless overridden at the user level.

4. Managing Organization Users

Property	Description	Values
orgId	Unique identifier for the organization	`1`
userId	Unique identifier for the user	`123`
role	Role assigned to the user within the organization	`Viewer`, `Editor`, `Admin`

Example: Adding a User to an Organization

const addUserToOrg = async () => {
  const response = await fetch("/api/org/users", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer <token>"
    },
    body: JSON.stringify({
      loginOrEmail: "user@example.com",
      role: "Editor"
    })
  });

  const result = await response.json();
  console.log("User added:", result);
};

Example: Updating User Role

const updateUserRole = async () => {
  const response = await fetch("/api/org/users/123", {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer <token>"
    },
    body: JSON.stringify({
      role: "Admin"
    })
  });

  const result = await response.json();
  console.log("Role updated:", result);
};

Example: Removing a User from Organization

const removeUserFromOrg = async () => {
  const response = await fetch("/api/org/users/123", {
    method: "DELETE",
    headers: {
      "Authorization": "Bearer <token>"
    }
  });

  const result = await response.json();
  console.log("User removed:", result);
};

Note: User roles in Grafana are managed at the organization level and can be Viewer, Editor, or Admin.

Warning: Removing a user from an organization does not delete their account; it only revokes their access to that organization.

5. Setting Organization Quotas

Quota Type	Configuration Key	Description	Default Value
org.users	`org.users`	Maximum number of users allowed in the organization	100
org.alerts	`org.alerts`	Maximum number of alerts that can be created	1000
org.datasources	`org.datasources`	Maximum number of data sources that can be added	10
org.dashboard	`org.dashboard`	Maximum number of dashboards allowed per organization	100
org.folder	`org.folder`	Maximum number of folders that can be created	50
org.apikeys	`org.apikeys`	Maximum number of API keys per organization	10

Example: Setting Organization Quotas via Config File

org:
  users: 150
  alerts: 2000
  datasources: 20
  dashboard: 200
  folder: 100
  apikeys: 20

Note: Quota settings can also be managed via the Grafana UI under Configuration > Organizations.

6. Configuring Default Organization

Property	Value	Description
defaultOrgId	`1`	Identifier of the default organization
defaultOrgName	`Main Org.`	Name of the default organization

Example: Setting Default Organization via Config

[auth]
; Set the default organization ID
default_org_id = 1

; Set the default organization name
default_org_name = "Main Org."

Note: Changes to default organization settings require a Grafana server restart to take effect.

7. Transferring Resources Between Orgs

Transferring resources between Grafana organizations is a critical operation for managing data and access across teams. The following table outlines the available methods and considerations:

Resource Type	Transfer Method	Notes
Dashboards	`API`	Use the Grafana API to export and re-import dashboards. Requires appropriate permissions in both source and target organizations.
Datasources	`API`	Recreate datasources in the target organization. Configuration must be updated to reflect new environment settings.
Alerts	`API`	Export alert rules via API and re-import into the target organization. Ensure notification channels are configured in the new org.
Folders	`API`	Folders can be exported and imported using the Grafana API. Permissions must be adjusted in the target organization.
Users	`Manual`	Users must be manually added to the target organization. Permissions and roles must be re-assigned.

Example: Transferring a Dashboard via API

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -X GET "http://grafana.example.com/api/dashboards/uid/<dashboard_uid>"

Example: Re-importing Dashboard to New Org

curl -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -X POST "http://grafana.example.com/api/dashboards/db" \
     -d '{"dashboard": <dashboard_json>, "folderId": 0, "overwrite": true}'

Note: When transferring dashboards, ensure that all referenced datasources and variables are compatible in the target organization.

Warning: Transferring resources does not automatically carry over user permissions. Permissions must be manually re-assigned in the target organization.

8. Using Organization API

Endpoint	Method	Description	Notes
/api/org	`GET`	Get current organization details	Returns organization info including name, ID, and settings
/api/org	`PUT`	Update current organization	Allows modification of org settings like name and address
/api/org/users	`GET`	List organization users	Retrieve all users in the current organization
/api/org/users	`POST`	Add user to organization	Adds a new user with specified role (Viewer, Editor, Admin)
/api/org/users/:userId	`DELETE`	Remove user from organization	Deletes a specific user from the organization

Example: Get Current Organization Info

curl -H "Authorization: Bearer <API_TOKEN>" \
     http://localhost:3000/api/org

Example: Update Organization Name

curl -X PUT \
     -H "Authorization: Bearer <API_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"name": "New Org Name"}' \
     http://localhost:3000/api/org

Example: Add User to Organization

curl -X POST \
     -H "Authorization: Bearer <API_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{"loginOrEmail": "user@example.com", "role": "Editor"}' \
     http://localhost:3000/api/org/users

Note: API tokens must have appropriate permissions to manage organization settings and users.

9. Setting Organization Address

Field	Description	Example Value	Required
address1	Primary street address line	`123 Main Street`	Yes
address2	Secondary street address line (e.g., apartment number)	`Suite 456`	No
city	City name	`New York`	Yes
state	State or province	`NY`	Yes
zipCode	Postal or ZIP code	`10001`	Yes
country	Country name or code (ISO 3166-1 alpha-2)	`US`	Yes

Example: Setting Organization Address via API

{
  "address1": "123 Main Street",
  "address2": "Suite 456",
  "city": "New York",
  "state": "NY",
  "zipCode": "10001",
  "country": "US"
}

Note: The organization address is used for billing and compliance purposes. Ensure all fields are filled accurately to avoid issues with invoices or regulatory reporting.

10. Isolating Data Between Organizations

Feature	Description	Notes
Organization isolation	Each organization has its own data, dashboards, and users	Ensures complete separation of concerns
User permissions	Users are scoped to specific organizations	Access control per organization
Data sources	Each organization can define its own data sources	Isolated from other organizations
Dashboards and folders	Dashboard visibility is restricted to organization members	Can be shared within the org only

Example: Creating a new organization

curl -X POST "http://localhost:3000/api/orgs" \
  -H "Authorization: Bearer <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp"}'

Note: Organization-level data is completely isolated and cannot be accessed by users from other organizations.

Warning: Changing organization membership requires appropriate permissions and can impact data access.