Creating Your First App User

Now that you've configured your app to use server-to-server authentication, you are ready to begin using Box Platform. In this tutorial, you will learn to create your first App User, as well how to manage App Users within an enterprise.

What are App Users?

App Users are full-featured enterprise Box accounts that belong to your application, ​not a Box end-user. Unlike typical Box accounts, these accounts do not have an associated login and can only be accessed through the Content API by the controlling application and associated Box User ID. This new user model allows your application to take advantage of groups, permissions, collaborations, comments, tasks, and the many other features offered by the Box platform.

Enterprise Tokens and App User Tokens

App Auth allows your application to request OAuth2.0 access tokens necessary to make calls to the Box Content API. Your application may request an enterprise access token or a user access token.

The table below describes the difference between the two types of tokens:

Enterprise Token
User Token

Used to create and manage users and to performing admin-level tasks

Used to perform user-based actions on behalf of an App User

  • Create, Manage, and Delete App Users
  • Edit App User Information
  • Configure Enterprise Settings
  • Manage Groups
  • Manage Retention Policies
  • Retrieve Admin Events
  • Manage Files and Folders
  • Upload and Download Files and Folders
  • Share Content with Users and Groups
  • Search for Available Content
  • Create and Assign Tasks
  • Comment on Files

1. Request an Enterprise Token

Creating App Users and Managing Your Enterprise

Using the Enterprise Access Token, you can create new App Users for your enterprise, as well as manage groups and other enterprise settings. To request this token, you will need to use the JWT grant specifying "enterprise" as the box_sub_type and the enterprise_id as the sub. The Enterprise ID is listed in the main page of the Admin Console and is the Enterprise in which your application was authorized.

Alternatively if you scroll down to the bottom of the configuration section in the developer console, you can download a JSON blob of your application settings.

2. Create an App User

Once you have received an Enterprise Access Token, you can make a POST request for a new App User. To do this, you must specify a “name” for the user (the only requirement is that this must be a string). The following attributes must be set to create an app user:

  • is_platform_access_only must be set to true
  • name is required, which can be any string and is shown in the web app as Display Name

Required Fields

'name' and 'is_platform_access-only' are required fields for creating an App User.

Note that 'name' is NOT a unique identifier.

POST /users
curl https://api.box.com/2.0/users \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name": "Ned Stark", "is_platform_access_only": true}' \
-X POST
{
    "type": "user",
    "id": "236506102",
    "name": "Ned Stark",
    "login": "AppUser_59659_vuNs7OCQ7y@box.com",
    "created_at": "2015-04-20T20:09:59-07:00",
    "modified_at": "2015-04-20T20:09:59-07:00",
    "language": "en",
    "timezone": "America/Los_Angeles",
    "space_amount": 5368709120,
    "space_used": 0,
    "max_upload_size": 16106127360,
    "status": "active",
    "job_title": "",
    "phone": "",
    "address": "",
    "avatar_url": ""
}

No Login Required

The login field can no longer be set for an application user. App Users are identified by their unique User ID, meant to be mapped to your external identity.

3. Request an App User Token

Once you have created an App User, you can request a User Access Token via the App Auth feature, which will return the OAuth 2.0 access token for the specified App User. This token is used to take user-specific actions (e.g., upload/download content, make comments, assign tasks, share with other users, etc.).

To request this token, you will need to use the JWT grant specifying "user" as the box_sub_type and the user_id returned for the App User as the sub (shown in the example response above).

4. Upload a File

Once you've received the App User token, let's perform an action as the App User and upload a file. We need to do this as a multi-part form upload, which looks like this in cURL:

curl https://upload.box.com/api/2.0/files/content \
 -H "Authorization: Bearer APP_USER_TOKEN" -X POST \
 -F attributes='{"name":"Jon_Snow.jpeg", "parent":{"id":"0"}}' \
 -F file=@Jon_Snow.jpeg

Alert:

Don’t forget the “@” sign when indicating the filename. This tells cURL to read data from the file.

Upon success of uploading the file, you'll receive a similar response.

{
    "total_count": 1,
    "entries": [
        {
            "type": "file",
            "id": "66627202737",
            "file_version": {
                "type": "file_version",
                "id": "70082724165",
                "sha1": "d32df7c468a3a72a82664997d99724d55c001ec1"
            },
            "sequence_id": "0",
            "etag": "0",
            "sha1": "d32df7c468a3a72a82664997d99724d55c001ec1",
            "name": "Jon_Snow.jpeg",
            "description": "",
            "size": 39234,
            "path_collection": {
                "total_count": 1,
                "entries": [
                    {
                        "type": "folder",
                        "id": "0",
                        "sequence_id": null,
                        "etag": null,
                        "name": "All Files"
                    }
                ]
            },
            "created_at": "2016-05-22T21:22:54-07:00",
            "modified_at": "2016-05-22T21:22:54-07:00",
            "trashed_at": null,
            "purged_at": null,
            "content_created_at": "2016-05-22T21:22:54-07:00",
            "content_modified_at": "2016-05-22T21:22:54-07:00",
            "created_by": {
                "type": "user",
                "id": "252824705",
                "name": "app_user_3",
                "login": "AppUser_129371_7NT2CIaHH3@boxdevedition.com"
            },
            "modified_by": {
                "type": "user",
                "id": "252824705",
                "name": "app_user_3",
                "login": "AppUser_129371_7NT2CIaHH3@boxdevedition.com"
            },
            "owned_by": {
                "type": "user",
                "id": "252824705",
                "name": "app_user_3",
                "login": "AppUser_129371_7NT2CIaHH3@boxdevedition.com"
            },
            "shared_link": null,
            "parent": {
                "type": "folder",
                "id": "0",
                "sequence_id": null,
                "etag": null,
                "name": "All Files"
            },
            "item_status": "active"
        }
    ]
}

Congratulations! You've completed your first major task with an App User.

5. Delete an App User

To delete an App User, follow the same syntax as deleting a Box user from an enterprise account.

DELETE /users/{user id}
curl https://api.box.com/2.0/users/USER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-X DELETE
No JSON response; 204 status code

6. Get an App User's Details

Follows the same syntax as getting an enterprise user’s details.

GET /users/{user id}
curl https://api.box.com/2.0/users/USER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
{
    "type": "user",
    "id": "236506102",
    "name": "Ned Stark",
    "login": "AppUser_59659_vuNs7OCQ7y@box.com",
    "created_at": "2015-04-20T20:09:59-07:00",
    "modified_at": "2015-04-20T20:11:24-07:00",
    "language": "en",
    "timezone": "America/Los_Angeles",
    "space_amount": 5368709120,
    "space_used": 0,
    "max_upload_size": 16106127360,
    "status": "active",
    "job_title": "",
    "phone": "",
    "address": "",
    "avatar_url": ""
} 

Note:

You can also pass the USER_ID parameter with is_platform_access_only set as the fields parameter to check if the specified user is an App User.

curl https://api.box.com/2.0/users/USER_ID?fields=is_platform_access_only
-H "Authorization: Bearer ACCESS_TOKEN"
{
    "type": "user",
    "id": "236506102",
    "is_platform_access_only": true
}

7. Edit an App User's Details

The following attributes may be set or changed from their default values for an App User by making a PUT call to the users endpoint:

  • name
  • language
  • job_title
  • phone
  • address
  • status
  • timezone
  • space_amount

Note:

Other user attributes are not accessible for an App User.

PUT /users/{user id}
curl https://api.box.com/2.0/users/USER_ID \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{"name": "patient 35321"}' \
-X PUT
{
    "type": "user",
    "id": "236506102",
    "name": "patient 35321",
    "login": "AppUser_59659_vuNs7OCQ7y@box.com",
    "created_at": "2015-04-20T20:09:59-07:00",
    "modified_at": "2015-04-20T20:11:24-07:00",
    "language": "en",
    "timezone": "America/Los_Angeles",
    "space_amount": 5368709120,
    "space_used": 0,
    "max_upload_size": 16106127360,
    "status": "active",
    "job_title": "",
    "phone": "",
    "address": "",
    "avatar_url": ""
}

8. Next Steps

The power of App Users is the ability to make API calls to the Content API as an individual user, maintaining the content relationships, permissions, groups, and collaboration features offered by the Box platform.

All of the resources available via the Content API for standard Box users are now available to App Users as well. You can find documentation for these endpoints here.

Additionally you can explore our SDKs which you can use to accelerate the development process.

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





Creating Your First App User