Account API

Use the Account API to create and deactivate users, return a list of all site admins, and set and remove site admins.

import json, requests

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

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

Create users

For each user, provide a list of user objects in JSON that contains the username, email, and password.

This API can be invoked only by:

  • A site admin
  • A user with Manage users permissions

Request

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

headers = {"Authorization": "Bearer {0}".format(token)}
data = json.dumps(
  {
      "users": [
      {
        "username": "bob",
        "email": "bob@instabase.com",
        "password": "password1"
      },
      {
        "username": "alice",
        "email": "alice@instabase.com",
        "password": "password2"
      }
    ]
  }
)
resp = requests.post(api_root + "/users", headers=headers, data=data).json()

Response

{
	"status": "OK",
	"result": {
		"created_users": ["bob"],
		"error_details": {
			"FAILURE": ["alice"]
		}
	}
}

This API could also be invoked to create service accounts, in which case only the username and the user_type fileds are required.

Request

headers = {"Authorization": "Bearer {0}".format(token)}
data = json.dumps(
    {
        "users": [
        {
            "username": "foo",
        }
        "user_type": "service_account"
        ]
    }
)
resp = requests.post(api_root + "/users", headers=headers, data=data).json()

Response

{
    "status": "OK",
    "result": {
        "created_users": ["foo"],
        "error_details": {}
    }
}

Deactivate users

This API request blocks an existing user from logging in or using APIs and removes the user from all teams and organizations.

This API can be invoked only by:

  • A site admin
  • A user with Manage users permissions

Request

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
resp = requests.post(api_root + "/<username>/deactivate", headers=headers).json()

Response

If successful:

{
  "status": "OK"
}

If the specified user owns teams or organizations, deactivation will fail.

{
  "status": "ERROR", "msg": "janedoe1 still owns teams. Failed to deactivate"
}

Disable users

This API request blocks an existing user from logging in or using APIs. Disabled accounts retain their access to entities such as spaces, subspaces, and groups. If a disabled account is reactivated, the user’s experience and access is the same as previously configured.

This API can be invoked only by:

  • A site admin.
  • A user with Manage users permissions

Request

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
resp = requests.post(api_root + "/<username>/disable", headers=headers).json()

Response

When successful:

{
  "status": "OK"
}

Reactivate users

This reactivates a deactivated or disabled user. If the user was in a disabled state, the user’s ACLs were preserved and they will have access to all entities they were granted previously. If the user was deactivated, they will no longer have access to anything.

This API can be invoked only by:

  • A site admin
  • A user with Manage users permissions

Request

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
resp = requests.post(api_root + "/<username>/reactivate", headers=headers).json()

Response

When successful:

{
  "status": "OK"
}

Get site admins

This request returns a list of all site admins.

This API can be invoked only by a site admin.

Request

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
resp = requests.get(api_root + "/admins", headers=headers).json()

Response

If successful:

{
	"status": "OK",
	"admins": [
    {
      "email": "bob@instabase.com",
      "username": "bob",
      "is_admin": true,
      "is_active": true,
      "is_verified": true,
      "is_approved": true,
      "is_disabled": false,
      "registered_on": 1559798774
    }, {
      "email": "alice@instabase.com",
      "username": "alice",
      "is_admin": true,
      "is_active": true,
      "is_verified": true,
      "is_approved": true,
      "is_disabled": false,
      "registered_on": 1528087641
    }
  ]
}

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

  • admins: The list of Users and their metadata

Each User in the admins list contains:

  • email: The user’s email.
  • username: The user’s username.
  • is_admin: Indicates whether the user is a site admin or not.
  • is_active: Indicates whether the user account is active.
  • is_verified: Indicates whether the user’s account has been verified via their email.
  • is_approved: Indicates whether the user’s account has been approved by an admin.
  • is_disabled: Indicates whether the user’s account has been placed into a disabled state.
  • registered_on: The creation time of the user’s account in seconds in epoch.

Set site admins

This request sets all provided usernames with site admin privileges. Note that the usernames provided must be registered users.

This API can be invoked only by a site admin.

Request

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

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
args = {
  "usernames": ["walter", "jesse", "gus"]
}
data = json.dumps(args)
resp = requests.post(api_root + "/admins", headers=headers, data=data).json()

Response

If successful:

{
  "status": "OK"
}

If one or more usernames was not successfully updated, more detailed errors can be found in error_details. This error status contains a JSON list denoting usernames that failed to be updated and why.

{
  "status": "ERROR",
  "msg": "Failed to set all usernames to admin.",
  "error_details": {
    "jesse": "User (jesse) not found"
  }
}

Remove site admins

This request removes site admin privileges from the provided list of usernames.

This API can be invoked only by a site admin.

Request

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

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
args = {
  "usernames": ["glenn", "rick"]
}
data = json.dumps(args)
resp = requests.delete(api_root + "/admins", headers=headers, data=data).json()

Response

If successful:

{
  "status": "OK"
}

If one or more usernames was not successfully updated, more detailed errors can be found in error_details. This error status contains a JSON list denoting which usernames failed to be updated and why.

{
  "status": "ERROR",
  "msg": "Failed to unset all usernames from admin.",
  "error_details": {
    "glenn": "User (glenn) not found"
  }
}

List users

This API can be used to return a list of users that match filter parameters. Several search queries are supported by setting these fields in the request body.

  • email_domain_pattern: Search for users with an email that matches the specified domain, such as instabase.com.
  • username_prefix: Search for users with a username that match the specified prefix.
  • search_string: Search for users with a username or email that contain the specified string. If there are too many results, pagination through all the results is supported. The response indicates this with has_more = True and a next_offset value. The value in next_offset can be passed in as the offset in a subsequent query. The page size can also be specified by setting limit in the request.
  • get_all: Ignores all search filters and returns a list of all users on the platform. Supports pagination.
  • offset: For paginated searches, specify the offset to start from. Use the next_offset returned from previous responses.
  • limit: For paginated searches, specify the number of results to return. If unset, defaults to 500. The maximum is also 500.
  • include_disabled: If this field is set to true, disabled users are included in the results.
  • user_type: The type of user to retrieve. Valid values are user or service_account. The default value is user.

Request

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

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
args = {
  "search_string": "insta",
  "get_all": "false",
  "limit": 100,
  "offset": 5
}
data = json.dumps(args)
resp = requests.post(api_root + "/list_users", headers=headers, data=data).json()

Response

If successful:

{
  "status": "OK",
  "users": [
    {
      "email": "alice@instabase.com",
      "username": "alice",
      "is_admin": false,
      "is_active": true,
      "is_verfied": true,
      "is_approved": true,
      "is_disabled": false,
      "registered_on": 1618362000
    },
    {
      "email": "admin@instabase.com",
      "username": "admin",
      "is_admin": true,
      "is_active": true,
      "is_verfied": true,
      "is_approved": true,
      "is_disabled": false,
      "registered_on": 1618368000
    }
  ],
  "has_more": false,
  "next_offset": -1
}

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

  • users: The list of Users and their metadata

Each User in the users list contains:

  • email: The user’s email.
  • username: The user’s username.
  • is_admin: Indicates whether the user is a site admin or not.
  • is_active: Indicates whether the user account is active.
  • is_verified: Indicates whether the user’s account has been verified via their email.
  • is_approved: Indicates whether the user’s account has been approved by an admin.
  • is_disabled: Indicates whether the user’s account has been placed into a disabled state.
  • registered_on: The creation time of the user’s account in seconds in epoch.

Check account type

There are two types of accounts: user accounts and organization accounts. This API can be used to check whether an account name exists and which type it is.

Request

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
resp = requests.get(api_root + "<account_name>/type", headers=headers).json()

Response

If the account exists:

{
	"status": "OK",
	"account_type": "user"
}

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

  • account_type: The account type. Valid values are user or org.

Reset password

Use this API to reset a user’s password if the platform is using basic authentication (username/password). A user can call this to reset their own password, or this can be called by an admin to reset another user’s password. After the reset, the user will be logged out of all sessions.

This API can be invoked only by:

  • A site admin
  • A user with Manage users permissions
  • Any user to reset their own password

The <username> in the route is the username of the user whose password is to be reset.

If a user is resetting their own password, they will need to pass in both their new_password and their current password as old_password.

If an admin is resetting another user’s password, they only need to pass in the desired new_password.

Request

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

import json, requests

headers = {"Authorization": "Bearer {0}".format(token)}
args = {
  "new_password": "my-new-password!",
  "old_password": "my-old-password#"
}
data = json.dumps(args)
resp = requests.post(api_root + "<username>/reset_password", headers=headers, data=data).json()

Response

If the reset is successful:

{
	"status": "OK",
}