get_user

Look up ONE Box account by its exact login (the account's email address).

Answers "what is this account's state?" — the question behind a ticket that says "my Box account is disabled". Every other tool here reads the event stream or walks folders, so an account with no recent events is invisible to them; this is one request against the user directory and the only tool that answers about an account directly. Use it when a specific account is named. It cannot list, search or enumerate accounts: it takes one login and answers about that login only.

Args: login: The account's full Box login, i.e. its email address (someone@example.com) — not a display name, not a user id. Matched EXACTLY, case-insensitively. A partial login does not match.

This server is downstream of an identity provider, not the master. Read what comes back as "what Box currently believes", and compare it against the IdP's own record (which is authoritative for who the account is). A disagreement is the finding, and is usually drift on the Box side rather than a mistyped address:

• enterprise absent/null — the account is no longer in the enterprise (it has become a free personal account), so enterprise SSO no longer applies to it even though the IdP still authenticates the person. Box classes such an account as external and returns it only on a COMPLETE login match, which is exactly what this tool asks for — so it is reachable here, and a partial login would silently lose it.

• status other than active — the IdP authenticates, Box refuses.

• is_platform_access_only true — an App User, which cannot sign in interactively at all.

One drift this tool cannot find for you: the same person under a second login at another domain (an alias, or a duplicate left by a migration). filter_term prefix-matches the WHOLE term, so a search for alice@old.example can never return alice@new.example. Finding that would take a search on the local part alone, which is a prefix search over the directory and is refused here by design. Ask the identity provider which login it asserts, and look that one up.

Returns two shapes, distinguished by whether the lookup completed.

On a completed lookup:

• requested_login — what was asked for, echoed back.

• found — bool. The only field that says whether the account was found.

• user — the account when found is true, else null: id, name, login, status (active / inactive / …, the usual answer to "why can't I sign in"), role, enterprise, space_used / space_amount (quota exhaustion is another recurring cause), created_at, modified_at.

• other_prefix_hits — how many further accounts the prefix search matched. A COUNT ONLY: those are different accounts and are deliberately not identified, so this can never be used to browse the directory.

• search_hits — how many entries the search returned.

• capped — true when the search result was truncated, so found: false is inconclusive rather than negative (note says so).

• note — plain-language reading of the above.

Why the filtering matters: Box's filter_term is a prefix search over display name AND login, not a lookup, so it happily returns somebody else — a colleague whose display name starts with the same letters. user is therefore only ever an exact login match, no other hit is ever identified, and a term that is not email-shaped is refused before the request is made (a one-character term would otherwise return a page of real accounts).

On failure the other shape is returned: {"error": ...} (missing env / needs-login for an expired OAuth session / a Box API error), plus likely_cause when the failure was a permission one. found is absent from that shape on purpose — a failed lookup is not a negative answer, and must never be read as "no such account". Auth caveat: this server supports two auth modes, and under oauth the effective permission is the authorising user's. In oauth mode the requirement IS verified end-to-end: the app must hold the "Manage users" application scope (without it /2.0/users answers 403 even when the authorising user is a co-admin who can manage users), and a scope added in the Developer Console only reaches tokens from a fresh interactive authorisation — refresh-token rotation keeps the original grant's scopes. Under ccg the endpoint remains unverified for this server.