Accounts 🔗

Accounts provide an organization-level scope for Crunch.io customers. All Users belong to one and only one Account. Account managers can administer their various users and entities and have visibility on them.

Permissions 🔗

A user is an “account manager” if their account_permissions have admin_account set to True.

Account entity 🔗

The account entity is available on the API root following the Shoji views.account path, which will point to the authenticated user’s account.

If the account has a name, it will be available here, as well as the path to the account’s users.

Branding configuration for the account is also exposed here, through the palette and logo attributes.

If the authenticated user is an account manager, the response will include paths to these additional catalogs:

  • Account projects
  • Account teams
  • Account datasets

GET 🔗

GET /account/
{
  "element": "shoji:entity",
  "body": {
    "name": "Account's name",
    "id": "abcd",
    "oauth_providers": [
      {
        "id": "provider",
        "name": "Service auth"
      },
      {
        "id": "provider",
        "name": "Service auth"
      }
    ],
    "logos": {
      "small": "<URL>",
      "large": "<URL>",
      "favicon": "<URL>"
    },
    "templates": {
      "powerpoint": "<URL>"
    },
    "palette": {}
  },
  "catalogs": {
    "teams": "http://app.crunch.io/api/account/teams/",
    "projects": "http://app.crunch.io/api/account/projects/",
    "users": "http://app.crunch.io/api/account/users/",
    "datasets": "http://app.crunch.io/api/account/datasets/",
    "applications": "http://app.crunch.io/api/account/applications/"
  }
}

PATCH 🔗

PATCH this endpoint to change the branding-related palette attribute. Logos for the account are controlled by the logo/ subresource (see below).

Attribute Type Description
palette object Contains three colors, primary, secondary and message, under the brand attribute to theme the account

Change account templates 🔗

POST /account/templates/

To set/change the account’s templates, the client needs to make a multipart/form-data request containing file fields for any of the supported template formats (currently only powerpoint). Only account admins are authorized to change this resource.

POST /account/templates/ HTTP/1.1
Content-Type: multipart/form-data; boundary=----------123456789
Content-Length: 500326

xxxxxxxxxx
----------123456789
Content-Disposition: form-data; name="powerpoint"; filename="template-powerpoint.pptx"
Content-Type: application/vnd.openxmlformats-officedocument.presentationml.presentation

xxxxxxxxxx
----------123456789--

HTTP/1.1 204

The server will update the templates accordingly. Currently, the only valid file extension is “pptx” for PowerPoint templates.

Remove account templates 🔗

It is possible to remove the templates that have been set up. To do so, PATCH back the contents of the template/ resource with the specific templates that need to be removed set to the null value.

Please note that currently only powerpoint templates are supported. Other template formats might be added in the future.

PATCH /account/templates/
"element": "shoji:view",
"value": {
  "powerpoint": null,
}

A 204 response will be returned on success. Only account admins are authorized to remove templates this way.

Applications 🔗

GET /account/applications/

GET returns a Shoji Catalog with the list of all the configured subdomains an account has.

{
    "element":"shoji:catalog",
    "index": {
        "./mycompany/": {}
    }
}

POST a Shoji Entity here to make a new application. The subdomain:

  • must be unique system-wide, case insensitive
  • can only contain letters, numbers, and - (dash)
  • must be between 3 and 32 characters in length
  • cannot start with - or a number

If the requested subdomain is unavailable or invalid, the server will return a 400 response.

{
    "element": "shoji:entity",
    "body": {
      "name": "my company",
      "subdomain": "mycompany",
      "palette": {
          "brand": {
                "primary": "#FFAABB", // Color of links, interactable things
                "secondary": "#G4EEBB", // Titles and such
                "message": "#BAA5E7"
            }
      },
      "manifest": {}
    }
}

Attributes name and subdomain are required; palette and manifest are optional. Note that you cannot specify logos in the POST request. Use the created entity’s logo/ resource to upload the image files to the app (see below).

Application entity 🔗

GET /account/applications/app_id/

GET this endpoint for a Shoji Entity containing all details about the configured application.

{
    "element":"shoji:entity",
    "body": {
        "name": "Application name",
        "subdomain": "mycompany",
        "logos": {
            "small": "<URL>",
            "large": "<URL>",
            "favicon": "<URL>"
        },
        "palette": {
            "brand": {
                "primary": "#FFAABB", // Color of links, interactable things
                "secondary": "#G4EEBB", // Titles and such
                "message": "#BAA5E7"
            }
        },
        "manifest": {}
    },
    "views": {
        "logo": "https://app.crunch.io/api/account/applications/mycompany/logo/"
    }
}

PATCH this endpoint to change the name, palette, or manifest. Logos are controlled by the logo subresource.

Attribute Type Description
name string Name of the configured application on the given subdomain
logo object Contains three attributes, large, small and favicon, with different resolution company logos
palette object Contains three colors, primary, secondary and message, under the brand attribute to theme the web app
manifest object Optional, contains further client configurations

Account users 🔗

Provides a catalog of all the users that belong to this account. Any account member can GET, but only account managers can POST/PATCH on it.

GET 🔗

GET /account/users/
{
  "element": "shoji:catalog",
  "index": {
    "http://app.crunch.io/api/users/123/": {
      "id_method": "pwhash",
      "id_provider": null,
      "email": "email@example.com",
      "name": "Steve Austin",
      "dataset_permissions": {
        "view": true,
        "edit": false
      },
      "account_permissions": {
        "admin_account": false,
        "create_datasets": false
      }
    },
    "http://app.crunch.io/api/users/234/": {
      "id_method": "pwhash",
      "id_provider": null,
      "email": "email1@example.com",
      "name": "Shawn Michaels",
      "dataset_permissions": {
        "view": true,
        "edit": true
      },
      "account_permissions": {
        "admin_account": true,
        "create_datasets": true
      }
    },
    "http://app.crunch.io/api/users/345/": {
      "id_method": "oauth",
      "id_provider": "google",
      "email": "email2@example.com",
      "name": "Rocky Maivia",
      "dataset_permissions": {
        "view": true,
        "edit": true
      },
      "account_permissions": {
        "admin_account": false,
        "create_datasets": true
      }
    }
  }
}

POST 🔗

Account members can POST to the account’s users catalog to create new users. If the a user with the provided email address already exists in the application (on another account), the server will return a 400 response.

POST /account/users/
{
  "element": "shoji:entity",
  "body": {
      "email": "new_email@example.com",
      "name": "Initial name",
      "account_permissions": {
        "admin_account": false,
        "create_datasets": true
      },
      "teams": ["<list of team urls>"],
      "projects": ["<list of project urls>"],
      "id_method": "pwhash/oauth",
      "id_provider": "",
      "send_invite": true
  }
}

It is possible to create a user to belong to different teams or projects by including those teams or projects’ urls in the payload, for example:

{
  "element": "shoji:entity",
  "body": {
      "email": "new_email@example.com",
      "name": "Initial name",
      "account_permissions": {
        "admin_account": false,
        "create_datasets": true
      },
      "teams": ["https://app.crunch.io/api/teams/abc/", "https://app.crunch.io/api/teams/123/"],
      "projects": ["https://app.crunch.io/api/projects/def/"],
      "id_method": "pwhash"
  }
}

The teams and projects attributes are optional and can be omited or empty lists.

PATCH 🔗

PATCH to the users’ catalog allows account admins to edit users’ permissions in batch. It is only possible to change the account_permissions attribute. Additionally, it is possible to delete users from the account by sending null as their tuple.

PATCH /account/users/
{
  "element": "shoji:catalog",
  "index": {
    "http://app.crunch.io/api/users/123/": {
      "account_permissions": {
        "admin_account": false,
        "create_datasets": false
      }
    },
    "http://app.crunch.io/api/users/234/": null
  }
}

Account datasets 🔗

Only account managers have access to this catalog. It is a read only shoji catalog containing all the datasets that users of this account have created (potentially very large catalog).

Account managers have implicit editor access to all the account datasets.

GET /account/datasets/
{
  "element": "shoji:catalog",
  "index": {
        "https://app.crunch.io/api/datasets/cc9161/": {
            "owner_name": "James T. Kirk",
            "name": "The Voyage Home",
            "description": "Stardate 8390",
            "archived": false,
            "size": {
                "rows": 1234,
                "columns": 67
            },
            "is_published": true,
            "id": "cc9161",
            "account": "https://app.crunch.io/api/accounts/123456/",
            "owner_id": "https://app.crunch.io/api/users/685722/",
            "start_date": "2286",
            "end_date": null,
            "streaming": "no",
            "creation_time": "1986-11-26T12:05:00",
            "modification_time": "1986-11-26T12:05:00",
            "current_editor": "https://app.crunch.io/api/users/ff9443/",
            "current_editor_name": "Leonard Nimoy"
        },
        "https://app.crunch.io/api/datasets/a598c7/": {
            "owner_name": "Spock",
            "name": "The Wrath of Khan",
            "description": "",
            "archived": false,
            "size": {
                "rows": null,
                "columns": null
            },
            "is_published": true,
            "id": "a598c7",
            "account": "https://app.crunch.io/api/accounts/123456/",
            "owner_id": "https://app.crunch.io/api/users/af432c/",
            "start_date": "2285-10-03",
            "end_date": "2285-10-20",
            "streaming": "no",
            "creation_time": "1982-06-04T09:16:23.231045",
            "modification_time": "1982-06-04T09:16:23.231045",
            "current_editor": null,
            "current_editor_name": null
        }
  }
}

Account projects 🔗

This catalog is available for account managers and lists all the projects that the users have created. Account managers have implicit edit access on all projects.

GET /account/projects/
{
  "element": "shoji:catalog",
  "index": {
        "https://app.crunch.io/api/projects/cc9161/": {
          "name": "Project 1",
          "id": "cc9161",
          "owner": "http://app.crunch.io/api/users/abcdef/"
        },
        "https://app.crunch.io/api/projects/a598c7/": {
          "name": "Project 2",
          "id": "a598c7",
          "owner": "http://app.crunch.io/api/users/123456/"
        }
  }
}

Account teams 🔗

This catalog is available for account managers and lists all the teams that the users have created. Account managers have implicit edit access on all teams.

GET /account/teams/
{
  "element": "shoji:catalog",
  "index": {
        "https://app.crunch.io/api/teams/cc9161/": {
          "name": "Team 1",
          "id": "cc9161",
          "owner": "http://app.crunch.io/api/users/123456/"
        },
        "https://app.crunch.io/api/teams/a598c7/": {
          "name": "Team 2",
          "id": "a598c7",
          "owner": "http://app.crunch.io/api/users/123456/"
        }
  }
}

Account Collaborators 🔗

An account collaborator is a Crunch.io user that is not a member of your account and has access to some/any of your account’s datasets.

Account admins can visit the account’s collaborators catalog to view the list of all collaborators for all datasets of the account.

GET /account/collaborators/

This catalog lists all the users that are not members of the account that have access to any of the account’s datasets, projects or teams.

Each element in the catalog tuple links to the user’s entity endpoint and has the name and email attribute.

{
  "element": "shoji:catalog",
  "index": {
        "https://app.crunch.io/api/users/cc9161/": {
          "name": "John doe",
          "email": "user1@example.com",
          "active": true,
        },
        "https://app.crunch.io/api/users/a598c7/": {
          "name": "John notdoe",
          "email": "user2@example.com",
          "active": true,
        }
  }
}

Collaborators order 🔗

GET /account/collaborators/order/

It is possible to group collaborators using a Shoji order.

It is possible to PATCH the graph attribute with a standard shoji order payload indicating the groups and collaborators (user URLs) for each group.

Collaborators datasets 🔗

The full list of datasets a collaborator has access to is available through its user’s entity endpoint by following the visible_datasets catalog.