How to Automate User Offboarding with Fastio API

When employees or contractors leave your organization, you need to revoke their access everywhere at once. Relying on an administrator to manually click through dashboards is risky. It often leaves orphaned API keys and active agent sessions running in the background.

AI agents make this even riskier. Fastio is an intelligent workspace where agents and humans work together. Because Fastio provides 251 MCP tools for agentic workflows, an active token gives full access to your organization's data. If someone forgets to revoke a long-lived API token, a former contractor's local OpenClaw installation could still access sensitive files.

An automated offboarding script fixes this. By calling a specific sequence of API endpoints, you can ensure every session stops, every token is invalidated, and every file moves to a manager. This approach also leaves a clear trail for compliance audits.

Helpful references: Fastio Workspaces, Fastio Collaboration, and Fastio AI.

Before writing the script, you need to set up your admin environment. You need an organization admin token with the org:admin and users:manage scopes. Generate this token specifically for your identity provider integration instead of tying it to a personal admin account.

Keep this credential in your secret manager. The script runs a sequence of operations that are hard to reverse. If you remove a user before reassigning their files, those files become orphaned and you have to recover them manually.

You also need a service account or admin user ID to receive the departing user's files. Every Fastio workspace needs an owner. When you remove a workspace, you are actually transferring ownership of that container and its Intelligence Mode index to a new owner.

The first step is freezing the account. Find the user's ID and stop them from generating new tokens. This prevents them from starting a new session while your script runs.

Send a PUT request to the /api/v1/users/{user_id}/status endpoint with the status set to suspended. This instantly stops the user from logging into the web UI or getting new OAuth tokens.

After suspending the account, find out what they own. Call the /api/v1/users/{user_id}/workspaces endpoint to get a list of every workspace under their account. Save this list in memory since you need these workspace IDs for the transfer phase.

Suspending the account first keeps the workspace list from changing. That way, your script won't miss any files the user created.

Give Your AI Agents Persistent Storage

Create an intelligent workspace where agents and humans collaborate securely. Get 50GB of free storage with the agent tier. Built for how automate user offboarding with fast api workflows.

Sign Up Free

Suspending an account stops new logins, but existing sessions might stay active until they expire. To be safe, you need to revoke all active permissions. This means terminating both web sessions and agent connections.

Send a POST request to /api/v1/users/{user_id}/sessions/revoke-all. This drops all active Streamable HTTP and SSE connections right away. If an agent is uploading a large file with the user's credentials, the transfer will fail with an authorization error.

Next, clear their specific API tokens by making a DELETE request to /api/v1/users/{user_id}/tokens. This removes the persistent credentials typically used in local automation scripts or CI/CD pipelines. Together, suspending the account and revoking sessions completely locks the user out of Fastio.

To transfer all files from a user, you have to reassign their workspaces. Fastio uses workspaces as the main boundary for humans and AI agents to work together.

Loop through the list of workspaces you grabbed in the first step. For each one, send a POST request to /api/v1/workspaces/{workspace_id}/transfer. Include the new_owner_id in the payload.

This reassigns the workspace and everything inside it. Since Fastio intelligence is built-in, the RAG index and semantic search transfer to the new owner automatically. If the departing user was on the free agent tier provides 50GB storage, that storage usage shifts to the new owner's quota right away.

Transferring workspaces automatically keeps projects moving. The new admin gets instant access to the files and can invite other people to take over the work.

The final step is removing the user from your organization entirely. You do this using the organization members endpoint.

Send a DELETE request to /api/v1/orgs/{org_id}/members/{user_id}. This removes them from the company directory and revokes any specific access they had to other shared workspaces.

Once the script finishes, you should verify it worked. Query the /api/v1/audit-logs endpoint and filter by the user ID and the user.deleted event. Checking this log confirms the offboarding was successful and gives you a clear record for compliance.

Agentic workflows create a few edge cases during offboarding. For example, an agent might hold an active file lock to stop other agents from editing a file at the same time.

When you revoke a user's sessions, Fastio automatically releases any file locks held by their agent tokens. But if the agent set up webhook subscriptions, you might need to clean those up manually. Query the /api/v1/webhooks endpoint to find and delete any subscriptions linked to the former user's apps.

If your team uses OpenClaw integrations, keep in mind that agent identities are usually tied to human accounts. When you offboard the human, any local agent using the ClawHub Fastio skill with their token loses access. Let the new workspace owner know so they can generate fresh credentials for those shared AI assistants.

You can build a Python script to handle these API calls. This script becomes your main tool for handling offboarding. Using the standard requests library, you can write the four-step sequence and add basic error handling.

Writing it this way makes it easy to connect the script to your HR systems. When an employee's status changes in your directory, a webhook can trigger your Python code. This revokes their Fastio access at the exact same time they lose access to their email.

Make sure to use exponential backoff for your network requests. If the workspace transfer endpoint times out because of a large file index, your script needs to wait and try again instead of moving on. If you delete the user before transferring their assets, their files will be orphaned.

You can connect your Python script to your identity provider so you don't have to run it manually. Tools like Okta and Entra ID send webhooks when an admin deprovisions an account. Your server catches that event, grabs the user's email, and matches it to their Fastio user ID.

After matching the ID, the server runs your Fastio API sequence. The exact moment a user is marked inactive in your directory, their Fastio sessions end and their workspaces transfer to a manager.

This setup saves your IT team a lot of time. It also ensures the offboarding process runs the same way every time, removing the risks that come with manual checklists.

Using the API is much more consistent. When an admin handles offboarding manually, they might forget to transfer a workspace or miss a long-lived agent token. The API sequence handles the whole process right away, avoiding the delays of doing it by hand.

Speed matters during security incidents. If you think an account is compromised, a script can freeze it and drop all sessions in milliseconds. You can investigate the issue safely, knowing the attacker is locked out of your organization's data.

Also, the API sequence creates structured logs at every step. You get a clear record showing exactly when access was revoked, which makes compliance reporting and security audits much easier.