Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.box.com/llms.txt

Use this file to discover all available pages before exploring further.

When a user logs into a Box platform application with their SSO provider, the first step that should be taken is to see if that user already exists from a previous login attempt where a Box user record was already created. If a Box user is found you should , or make , to access Box APIs as that user. If a Box user is not found you should create a new user with an association to the SSO user record. To search for existing users the endpoint may be used. Depending on whether you’re using the external_app_user_id or login method your query will look slightly different.

​
Find user by external_app_user_id

To search for enterprise users by the stored external_app_user_id value you will need one piece of information from the SSO provider:
  • UID (required): The unique identifier from the SSO user record.
Once available, make a request to the list enterprise users endpoint, supplying the external_app_user_id definition in the parameters.
You can retrieve app users for a specific application only if such app users were created by this application. If you use one application to search for users created by a different one, no data will be returned.
const ssoUID = 'SSO User Unique ID';

// Check enterprise users for matching external_app_user_id against SSO UID
client.enterprise.getUsers({ "external_app_user_id": ssoUID })
.then((users) => {
    if (users.total_count > 0) {
        // User found, fetch user ID
        const userId = users.entries[0].id;
    } else {
        // User not found - create new user record
    }
});

​
Find user by email address

To search for enterprise users by their login email you will need one piece of information from the SSO provider:
  • Email (required): The unique email from the SSO user record.
Once available, make a request to the list enterprise users endpoint, supplying the email address as the filter_term, which is made available to search by email or name. 
const ssoEmail = 'ssouser@email.com';

client.enterprise.getUsers({filter_term: ssoEmail})
    .then(users => {
        if (users.total_count > 0) {
            // User found, fetch user ID
            const userId = users.entries[0].id;
        } else {
            // User not found - create new user record
        }
    });