Organization API

Site admins use the Organization API to manage your organization spaces.

See Instabase API authorization and response conventions for authorization, success response, and error response convention details.

For the Organization API, api_root defines where to route API requests for your Instabase instance:

import json, requests

api_root = "https://www.instabase.com/api/v1/organizations"

Create an organization

Use this API to create an organization space.

This API can be invoked only by:

Request

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'display_name': 'Eng Organization',
  'description': 'For all eng work',
}
data = json.dumps(args)
resp = requests.post(api_root + '/<org_name>', headers=headers, data=data).json()

The body of the request must be a JSON object with the following fields:

  • display_name: a user-friendly display name

  • description: a description for the organization

For each organization, org_name is a unique global handle that identifies the organization similar to how a username identifies a user.

The org_name is a part of the API route, where it must be:

  • composed only of alphanumeric characters and underscores

  • be 3 to 100 characters in length

Get organization information

Use this API to retrieve organization information, including the admins and members of the organization.

This API can be invoked only by:

Request

The request includes an optional Instabase-API-Args header that’s a JSON object with these fields:

  • get_all_members: true | false. If not set, the default value is false.

    • true: return the list of members in the organization space, excluding those inside groups

    • false: return all users and groups who are admins on the organization space

import json, requests

# headers
api_args = dict(
  get_all_members=True
)

headers = {
  'Authorization': 'Bearer {0}'.format(token),
  'Instabase-API-Args': json.dumps(api_args)
}
resp = requests.get(api_root + '/<org_name>', headers=headers).json()

Response

If successful:

{
  "status": "OK",
  "org": {
    "display_name": "Eng Organization",
    "description": "For all eng work",
    "is_admin": true,
    "admins": {
      "users": ["admin-user1"],
      "groups": ["admin-group1"]
    },
    "owner": "aaron"
  }
}

The body of the response is a JSON dictionary with the following fields:

  • display_name: a user-friendly display name

  • description: a description for the organization

  • is_admin: whether the user making the request has admin permissions on the org

  • admins: the users and groups who are admins of the organizations

  • members: the users and groups who are members of the organizations

  • owner: the original creator of the organization

Update organization

Use this API to update organization information such as the display name and description.

This API can be invoked only by:

Request

A request must provide a new display name, a new description, or both, to be successfully processed.

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'display_name': 'New Organization Display Name',
  'description': 'For all eng work'
}
data = json.dumps(args)
resp = requests.patch(api_root + '/<org_name>', headers=headers, data=data).json()

Delete organization

Use this API to delete an organization.

This API can be invoked only by a site admin.

Request

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
resp = requests.delete(api_root + '/<org_name>', headers=headers).json()

Update organization admins

Use this API to add users or groups as admins to an organization space.

This API can be invoked only by:

Request

Organization admins can be users or groups. Organization admins can add other admins, access all subspaces, and have read and write access to all metadata, including the ability to update and delete the organization. Use this API to add or remove users or groups as organization admins.

import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
args = {
  'perms':{
    'admin': {
      'users': {
        'user1': False, # Remove this user from being an admin
        'user2': True   # Make this user an admin
      },
      'groups': {
        'group1': False, # Remove this group from being an admin
        'group2': True   # Add this group as an admin
      }
    }
  }
}

data = json.dumps(args)
resp = requests.post(api_root + '/<org_name>/members', headers=headers, data=data).json()

Response

If one or more users wasn’t successfully added, more details are provided in error_details with a JSON dictionary that denotes which users failed to be added and why.

{
  "status": "ERROR",
  "msg": "Failed to add all members.",
  "error_details": {
    "user1": "User (user1) not found",
    "user2": "User (user2) not found"
  }
}

List all organizations

Use this API to return a list of all organization spaces across the entire site regardless of explicitly granted permissions.

This API can be invoked only by:

If other users use this API, the response returns a list of organizations they have access to.

Request

Supported query parameters are:

  • get_profiles: If true, returns profile information about the organization, such as the full name, the description and profile photo URL.
import json, requests

headers = {'Authorization': 'Bearer {0}'.format(token)}
resp = requests.get(api_root + '/admin/list_all?get_profiles=true', headers=headers).json()

Response

If successful:

{
    "status": "OK",
    "orgs": [
        {
            "name": "eng_org",
            "display_name": "Engineering",
            "description": "Instabase Engineers",
            "profile_photo_url": "https://eng.jpg",
            "is_admin": true,
            "owner": "adminuser"
        },
        {
            "name": "sales_org",
            "display_name": "Sales",
            "description": "Instabase Sales",
            "profile_photo_url": "https://sales.jpg",
            "is_admin": false,
            "owner": "salesperson"
        }
    ]
}

The body of the response is a JSON dictionary with the following fields:

  • orgs: The list of organizations and their metadata

Each organization in the orgs list contains:

  • name: The unique organization name.

  • display_name: The user-friendly display name, returned only if the request specified get_profiles=true.

  • description: The description for the organization, returned only if the request specified get_profiles=true.

  • profile_photo_url: The URL to the profile photo if set, returned only if the request specified get_profiles=true.

  • is_admin: Indicates whether the requesting user is an admin of the organization.

  • owner: The username of the original creator of the organization.