Organizations API

Manage organizations and organization membership

Organizations API

The Organizations API provides endpoints for managing Grafana organizations and their members.

Get Current Organization

Get the current organization for the authenticated user.

cURL

curl -X GET http://localhost:3000/api/org \
  -u admin:admin

{
  "id": 1,
  "name": "Main Org.",
  "address": {
    "address1": "123 Main St",
    "address2": "Suite 100",
    "city": "San Francisco",
    "zipCode": "94101",
    "state": "CA",
    "country": "USA"
  }
}

id · integer

Organization ID

name · string

Organization name

address · object

Organization address information

address.address1 · string

Address line 1

address.city · string

City

address.state · string

State or province

address.country · string

Country

Get Organization by ID

Retrieve an organization by its ID.

cURL

curl -X GET http://localhost:3000/api/orgs/1 \
  -u admin:admin

{
  "id": 1,
  "name": "Main Org.",
  "address": {
    "address1": "123 Main St",
    "city": "San Francisco",
    "zipCode": "94101",
    "state": "CA",
    "country": "USA"
  }
}

org_id · integer · required

Organization ID

Get Organization by Name

Retrieve an organization by its name.

cURL

curl -X GET http://localhost:3000/api/orgs/name/Main%20Org. \
  -u admin:admin

{
  "id": 1,
  "name": "Main Org.",
  "address": {
    "address1": "123 Main St",
    "city": "San Francisco"
  }
}

org_name · string · required

Organization name (URL encoded)

Create Organization

Create a new organization. Only works if users.allow_org_create is enabled in Grafana configuration.

cURL

curl -X POST http://localhost:3000/api/orgs \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Organization"
  }'

{
  "orgId": 2,
  "message": "Organization created"
}

name · string · required

Organization name

orgId · integer

ID of the newly created organization

message · string

Confirmation message

Update Current Organization

Update the current organization’s name.

cURL

curl -X PUT http://localhost:3000/api/org \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Org Name"
  }'

{
  "message": "Organization updated"
}

name · string · required

New organization name

Update Organization

Update an organization by ID.

cURL

curl -X PUT http://localhost:3000/api/orgs/1 \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Org Name"
  }'

{
  "message": "Organization updated"
}

org_id · integer · required

Organization ID

name · string · required

New organization name

Update Organization Address

Update the address for an organization.

cURL

curl -X PUT http://localhost:3000/api/org/address \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "address1": "456 New St",
    "address2": "Floor 3",
    "city": "New York",
    "zipCode": "10001",
    "state": "NY",
    "country": "USA"
  }'

{
  "message": "Address updated"
}

address1 · string

Address line 1

address2 · string

Address line 2

city · string

City

zipCode · string

ZIP or postal code

state · string

State or province

country · string

Country

Delete Organization

Delete an organization by ID.

cURL

curl -X DELETE http://localhost:3000/api/orgs/2 \
  -u admin:admin

{
  "message": "Organization deleted"
}

org_id · integer · required

Organization ID

You cannot delete your currently active organization. Switch to a different organization first.

Search Organizations

Search all organizations.

cURL

curl -X GET "http://localhost:3000/api/orgs?perpage=10&page=1&query=Main" \
  -u admin:admin

[
  {
    "id": 1,
    "name": "Main Org."
  }
]

perpage · integer · default: "1000"

Number of organizations per page

page · integer · default: "1"

Page number

query · string

Search query (searches organization name)

name · string

Filter by exact organization name

Get Organization Users

Get all users in the current organization.

cURL

curl -X GET http://localhost:3000/api/org/users \
  -u admin:admin

[
  {
    "orgId": 1,
    "userId": 1,
    "email": "admin@localhost",
    "login": "admin",
    "role": "Admin",
    "avatarUrl": "/avatar/abc123"
  }
]

userId · integer

User ID

email · string

User email

login · string

Username

role · string

Organization role: “Admin”, “Editor”, or “Viewer”

Add User to Organization

Add a user to the current organization.

cURL

curl -X POST http://localhost:3000/api/org/users \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "loginOrEmail": "[e-mail]",
    "role": "Editor"
  }'

{
  "message": "User added to organization"
}

loginOrEmail · string · required

Username or email of the user to add

role · string · required

Role to assign: “Admin”, “Editor”, or “Viewer”

Update User in Organization

Update a user’s role in the current organization.

cURL

curl -X PATCH http://localhost:3000/api/org/users/2 \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "role": "Admin"
  }'

{
  "message": "Organization user updated"
}

userId · integer · required

User ID

role · string · required

New role: “Admin”, “Editor”, or “Viewer”

Remove User from Organization

Remove a user from the current organization.

cURL

curl -X DELETE http://localhost:3000/api/org/users/2 \
  -u admin:admin

{
  "message": "User removed from organization"
}

userId · integer · required

User ID to remove

Permissions

If you are running Grafana Enterprise with Fine-grained access control enabled:

• Read organization: Requires orgs:read permission
• Create organization: Requires orgs:create permission
• Update organization: Requires orgs:write permission
• Delete organization: Requires orgs:delete permission
• Manage org users: Requires org.users:add, org.users:write, or org.users:remove permissions