Authentication
Authenticate a client and send bearer tokens to the Fluso REST API.
The REST API base URL is https://api.fluso.ai. Set it once, then assign the access token returned by the client sign-in flow:
The /v1 routes in this Beta section are the current client surface and may change during beta. Endpoints used only by the Fluso web app are internal and may change without notice.
export FLUSO_API=https://api.fluso.ai
export FLUSO_TOKEN='<access-token>'Send that token on every authenticated request:
Authorization: Bearer $FLUSO_TOKENKeep access and refresh tokens out of source control. The examples below use placeholders and environment variables.
Once authenticated, start with Agents and versions.
Start client sign-in
/v1/auth/client/startCreates a short-lived browser sign-in URL for a CLI or another client.
curl "$FLUSO_API/v1/auth/client/start" \
-H 'Content-Type: application/json' \
-d '{
"client": "cli",
"client_user_id": "device-123",
"metadata": {"return_to": "fluso://auth"}
}'{
"url": "https://<portal-host>/auth/client/launch?state=...",
"expires_in": 600
}Open url in the user's browser. The signed-in page completes approval and returns a one-time code to the client.
Exchange the one-time code
/v1/auth/client/exchange/{code}Consumes the code once and returns credentials bound to the same client and client user ID.
export FLUSO_CODE='<one-time-code>'
curl "$FLUSO_API/v1/auth/client/exchange/$FLUSO_CODE?client=cli&client_user_id=device-123"{
"status": "completed",
"auth": {
"access_token": "<access-token>",
"refresh_token": "<refresh-token>",
"expires_in": 86400,
"aci_api_key": "<api-key>",
"user": {
"id": "22222222-2222-4222-8222-222222222222",
"email": "developer@example.com",
"name": "Developer"
}
}
}The code expires and cannot be exchanged twice.
Refresh a client session
/v1/auth/client/refreshExchanges a valid client refresh token for refreshed credentials.
curl "$FLUSO_API/v1/auth/client/refresh" \
-H 'Content-Type: application/json' \
-d '{"refresh_token":"<refresh-token>"}'{
"access_token": "<new-access-token>",
"refresh_token": "<new-refresh-token>",
"expires_in": 86400,
"aci_api_key": "<api-key>"
}Read the current user
/v1/auth/meReturns the user attached to the bearer token and their runtime API key.
curl "$FLUSO_API/v1/auth/me" \
-H "Authorization: Bearer $FLUSO_TOKEN"{
"user": {
"id": "22222222-2222-4222-8222-222222222222",
"email": "developer@example.com",
"name": "Developer",
"picture": null,
"created_at": "2026-08-31T09:00:00"
},
"aci_api_key": "<api-key>"
}Workspace and usage routes also expect the bearer header. An X-API-Key
header alone does not authenticate those proxy paths.
Next
Use the token with Agents and versions, or open a turn through Threads and messages.