How this fits with the React SDK
@athenaintel/react lists a person’s connected accounts and connects new ones: useAthenaConnectors and <ConnectButton>. These routes add what comes after: browsing a connected account and importing a file from it.
Every account useAthenaConnectors lists has a catalogId. That id is the catalog_asset_id these routes take.
useAthenaConnectors does not list Microsoft 365 accounts yet, and Microsoft 365 is the only connector these routes browse today.Who can call them
Call the routes with a credential the person holds themselves: their Athena sign-in, or an API key of their own. That is what an app built on@athenaintel/react holds for the person who created its computer, and for every member of an application.
A credential that a runtime holds for its person is refused with 403 before anything is read. That covers a computer’s own key, a session VM’s, a notebook’s, a preview’s and an agent’s run. It also covers the viewer credential a member gets inside someone else’s computer app.
Neither route depends on which workspace the person has open in Athena. Browsing and importing happen in the workspace the source belongs to. The person must be a member of that workspace.
Browse a connected account
Browsing is one route, used at every level. Each item says which catalog to name next.- List the connected account’s catalog. Its items are its sources: a OneDrive and the SharePoint sites the person connected.
- List a source’s
catalog_asset_id. A SharePoint site answers its document libraries. A OneDrive answers its top-level folders and files. - To open a library or a folder, list the same
catalog_asset_idwithfolder_idset to the item’sid.
kind says what was listed: microsoft_365 for a connected account, sharepoint_site or onedrive for a source.
When
next_page_token is not null, pass it back as page_token with the same catalog_asset_id and folder_id for the next page. Treat the token as opaque.
web_url is the item’s own address in SharePoint or OneDrive. Opening it asks for the person’s sign-in there.
The person needs a connected account of their own for a source. Seeing a colleague’s SharePoint catalog in Athena is not enough: the route answers
403 with code connect_your_own, and Athena asks Microsoft nothing.Import a file
201 with the new asset’s id.
- Folder.
folder_asset_idmust be a folder in the source’s workspace that the person can edit. Otherwise the route answers403or400and stores nothing. - Size. A file can be at most 100 MiB. A larger one is refused with
413and codefile_too_largebefore Athena reads any of it. - Who can open it. The new asset takes the sharing of where it is filed. Everyone who can open the Drive or the place the folder is in can open the asset, so import into a folder whose audience should see the file.
- The copy. A SharePoint file arrives as the same protected copy that Import a copy makes in Athena. It cannot be shared person by person, moved or renamed afterwards, and a share made on the folder itself for one person is not copied onto it. It keeps a record of the SharePoint file it came from.
- OneDrive. OneDrive files can be browsed but not imported yet. They are listed with
importable: false, and an import answers400with codeimport_not_supported.
Handle refusals
A refusal carries adetail object with a code and a message written for a person. Branch on code.
Some refusals carry a plain sentence in
detail instead of an object, so read detail as either. They are a credential the person does not hold themselves (403), a workspace that is no longer active (403), a destination folder they cannot see or edit (403) or that is archived or no folder (400), and a request body over 16 KiB (413).
A request that does not validate answers 422, and its detail is a list of the fields at fault.
What Athena keeps on its side
- The person’s Microsoft sign-in stays encrypted in Athena, on that person’s own connected account. Athena uses it for each call and never returns it.
- Microsoft decides what the person can see on every call, with their current permissions there.
- Browsing stores nothing. An import stores the new asset and its record of where the file came from.

