Service Accounts

A Service Account represents your application within a Box Enterprise and uses a server-to-server authentication with OAuth 2.0 and JSON Web Tokens (JWT).

Choosing Permissions for Your Service Account

A Service Account represents your application within a Box Enterprise. The permissions available to each Service Account are determined by the Application Scopes chosen in the Box Developer Console.

Making Requests as a Service Account

Making API requests as a Service Account is as easy as making calls for any other user via the Box API. However, because this is a programmatic user (accessible only via the API), you must use the OAuth 2.0 with JWT grant in order to obtain an access token to make calls as the Service Account. For those familiar with Box Platform, this is known as the “Enterprise Token”.

Governing Your Service Account and its Content

Service Accounts are not visible to standard Box Users as they do not represent an individual user, but rather an application. To view the content of a Service Account, an Administrator can use* the Global Content Manager in the Box Admin Console to view the Service Account and all of its associated content.

Removing a Service Account

Removing a Service Account requires deleting the application and all of its associated content and users. To do this, navigate to Custom Apps in the Apps pages of the Box Admin Console.

Features of Service Accounts

  • Application Content Store - you can store content at the application level, rather than at the individual user level, by maintaining content within the Service Account. You can manage this content within the Box Admin Console.
  • Access to Any User - you can generate access tokens for both Managed Users and App Users or to make server-side calls using the As-User header to impersonate a user.
  • Flexible Application Scopes - Each Service Account is authorized for the specific set of scopes permitted by the application and authorized by the Admin.
  • Enterprise Features - Service Accounts can use admin-level capabilities (if authorized), such as managing and applying Retention Policies, setting and using Metadata Object, and accessing the Events endpoint of the Box Content API.
  • Application Recorded Events - Events are mapped directly to the application and its Service Account, which makes filtering event activity available via the Events API much easier.

Service Account Authentication

To make API calls using a Service Account, you have to authenticate using OAuth2 with JWT. You can perform actions on behalf of Managed Users and App Users using the As-User Header with the Enterprise Access Token.

Service Account Permissions

There are three different Service Account permissions levels:

Permission Level
Description

No Users

The service account does not have access to any users beyond the Service Account associated with the application.

App Users

Actions on behalf of App Users and the application associated with the Service Account.

All Users

Actions on behalf of Managed Users, App Users, and the application associated with the Service Account.

Service Account Limitations

  • A Service Account is an API-only account. It cannot be logged into through the Box web app.
  • You should not use Service Accounts to make client-side requests. It is designed for server-side integrations. If you need to make a client-side request, you can generate an access token scoped to an App User.

FAQ

1. What's the difference between a Service Account and an App User?

A Service Account represents your application within a Box Enterprise. Depending on the permission level, a Service Account also gives you control of App User accounts. An App User is a Box account that belongs to your Box Platform application. An App User access token can only access content from its own account.

2. What's the difference between a Service Account and an Admin?

A Service Account and an Admin are different account types, but they do have some overlap in functionality. Think of a service account as an application account. It has its own application level content store and can perform Admin actions such as creating users, metadata templates, and groups.

It does not use the As-User header for its own authentication, but can do so for users if the Service Account is set up with the appropriate scopes ("All Users" user access scope and "Perform actions on behalf of users" advanced features scope).

3. How can I increase the rate limit of my Service Account?

Box API rate limits are scoped to individual accounts. You can increase the overall rate limit for your Service Account by making API calls on behalf of other accounts. You can make calls on behalf of both Manged Users and App Users using the As-User Header.

Questions
If you have any questions, please visit our developer forum.


Service Accounts