A critical part of planning and developing an application is understanding the types of users involved. There are four main types of users: managed (internal and external), admin, service account, and app users. Let's take a closer look at the differences.
The Box Admin is the principal Box account administrator. They can make additional co-admins with similar or more restrictive administrative privileges. Admins and Co-Admins can directly edit, delete, enforce security settings, and run reports against these users via the Admin Console.
Each Box enterprise is assigned a unique enterprise ID. Managed Users are any users that belong to one enterprise ID. Managed Users consume a standard Box license and often, but not always, share the same email domain.
An externally managed user, or External User, is a Managed User that belongs to a different enterprise ID. External users are often encountered when they are collaborated in on content owned by a Managed User of the application's enterprise, or when they authorize an OAuth 2.0 application. These users still have their own Box accounts, but cannot be managed via the Admin Console.
A Service Account provides developers with a programmatic authentication mechanism for server-side integrations with Box. In other words, an application can authenticate to Box as the service, which is represented by a Service Account user. A Service Account can then be used to create other application specific users, called App Users described further below.
A unique Box Service Account is automatically generated as soon as an
application, leveraging server authentication, is authorized in the
Admin Console. From that point forward, the Service Account represents the
application in the Box enterprise. Since every Box account must have an email
address, Box assigns one. The format will always be
AutomationUser_AppServiceID_RandomString@boxdevedition.com. For example:
AutomationUser_123456_6jCo6Pqwo@boxdevedition.com. This is why you may
sometimes hear the Service Account referred to as an Automation User.
The numbers surrounded by underscores are also unique to the application and are
called a Service ID. To locate a Service ID in the Developer Console,
click on the tile for an application and look at the URL. For example,
https://example.app.box.com/developers/console/app/123456. As you can see,
this application corresponds to the Service Account provided in the example
By default, most Service Accounts are allocated 10GB of storage. This is because
they abide by the storage allocation set in the New User Default Settings
found under the User Settings tab of the Admin Console. This amount may
differ based on whether an enterprise updated this setting or not. To
update the amount of storage allocated to a Service Account after its creation,
make an API call to the update user endpoint and pass in the
desired value, in bytes, using the
space_amount body parameter.
Once the Service Account is generated, a section is automatically added to the General tab of the Developer Console revealing the email address.
If someone attempts to make API calls using a Service Account Access Token
before the application is authorized in the Admin Console they will receive an
"error_description": "This app is not authorized by the enterprise"
- Distribution Publishing: upload and share files with any number of users whether or not they are authenticated
- On-Premises Systems and Devices: programmatically ingest content from on-premises systems and connected devices
- Content Migration and Monitoring: move content from on-premises to the cloud or between cloud providers
- Event Monitoring: monitors events in an enterprise to ensure compliance and or trigger workflows based on actions
- Content Archive: house minimally accessed content
The endpoints that a Service Account Access Token can successfully interact with are determined by the application scopes configured in the Developer Console. Depending on the granted scopes, a Service Account may have the ability to perform Admin actions.
Only Primary Admins have the ability to log in as a Service Account through the Content Manager in the Admin Console. To do this, use the Content Manager's search bar to locate the name of the application, right click on it, and select “Log in to user’s account”.
A Service Account can be thought of as having the permissions of a Box Co-Admin. Similar to co-admins being unable to manage each other, co-admins cannot log in as a Service Account user.
Service Accounts are not currently visible in the users and group tab of the Admin Console.
Because a Service Account represents an application as a user within the enterprise, it has its own folder tree and content ownership capabilities. By default this folder tree is empty because the Service Account does not initially own or collaborate on content. This is similar to when you first land on your All Files page in a newly provisioned Box account.
To collaborate a Service Account on existing content use the assigned email address to invite them as you would any other user. If you are instead adding the collaboration via the API you will need to use an Access Token for a user that already has access to the content and has the appropriate collaboration permissions to invite collaborators. You will also use the Service Account’s user ID, which is returned when making a call to the get current user endpoint using an Access Token for the Service Account.
A Service Account is also automatically generated when a Limited Access App is created in the Developer Console. This Service Account has some additional restrictions that a Service Account associated with a Custom App does not.
- All content used within the Limited Access App must be uploaded and owned by the Service Account
- The Service Account can not access any other user's information or content
- The Service Account can not create or otherwise manage any type of new user
- The Service Account can only access a subset of APIs related to previewing content
App users are only accessible via the API, meaning they do not have login credentials. They can be created by a Service Account and therefore are only applicable to applications leveraging server to server authentication. App Users are tied to the application used to create them, and while they can collaborate on content outside of the application, the user itself cannot be moved under another application.
App users are created using a Service Account access token to call the
create user endpoint. The
is_platform_access_only body parameter
must be set to true or a managed user is created instead.
Since every Box account must have an email address, Box assigns one. The format
will always be
The numbers surrounded by underscores are also unique to the application and
are called a Service ID. To locate a Service ID in the Developer Console,
click on on the tile for an application and look at the URL. For example,
https://exampl.app.box.com/developers/console/app/1234567 . As you can see,
this application corresponds to the App User in the example above.
App Users extend the functionality of Box’s Platform to applications serving any user, regardless of if they have an existing Box account. App users are often used by applications that manage their own user authentication, but want to store the data in unique Box user accounts.
- Customer Portals: Websites or applications where clients or patients can log in to access information provided by employees at a company and/or to store and retrieve their own sensitive documents.
- Vendor Portals: Content distribution sites for companies to provide materials including marketing collateral, price lists, product information, sales agreements or contracts, and other documents to vendors. Box's groups and permission model allow for companies to organize content for partners based on partner criteria and/or tier.
- Branded Customer Facing Applications: The ability to create App Users on behalf of an end-user allows companies to build seamless customer-facing features such as permissions, auditing, and reporting. This is particularly valuable for regulated industries such as Financial Services and Healthcare. Moreover, user-based data from our reporting capabilities allows developers to leverage analytic tools to better understand user behavior.
App Users cannot see or interact any content in the folder tree of the Service Account unless explicitly added as a collaborator. Again, because App Users does not have login credentials, they cannot access content outside of the Custom Application.
App users are accessible via the Users & Groups tab of the Admin Console. To filter for these users, use the view options button > Role > App Users.
App Users are also accessible through the Content Manager in the Admin Console.
Each App User has its own folder tree and content ownership capabilities. By default this folder tree is empty because they do not initially own or collaborate on content. This is similar to when you first land on your All Files page in a newly provisioned Box account.
To collaborate an App User on existing content use the assigned email address to invite them as you would any other user. If you are instead adding the collaboration via the API you will need to use an Access Token for a user that already has access to the content and has the appropriate collaboration permissions to invite collaborators.
If you are using OAuth 2.0, JWT, or CCG as the authentication method for your
application, it is possible to make what are called
as-user calls. This means
that even though you created an original connection to the Box API as yourself
or as a service account, you can make subsequent calls impersonating another
user. This is useful in automating administrative tasks like folder
reorganization or employee provisioning. In order to make
the appropriate scope must be added to the application when creating it
in the developer console. For example, in an OAuth 2.0 custom app, you
would need to turn on this switch.