Authentication & User Management Authentication methods, user CRUD, getting started patterns

Authentication Methods

All authenticated endpoints require: Authorization: Bearer {token}

The token can be a JWT (from Basic Auth or OAuth), an API key, or a 2FA-upgraded JWT.

Method 1: Basic Auth to JWT

Send HTTP Basic Auth (email:password) to get a JWT.

Returns auth_token (JWT). If the account has 2FA enabled, the returned token has limited scope until 2FA verification is completed.

Optional revocable=true — pass to mint a session-bound JWT that can be invalidated server-side via POST /current/user/auth/sign-out/. Recommended for browser sessions where users expect a logout button to terminate access. JWTs minted without revocable (the default) are stateless and sign-out has no effect on them — but ALL login tokens (with or without revocable) can still be killed via POST /current/user/auth/invalidate-all/, which terminates every login session for the user. See the session-termination endpoints (sign-out / invalidate-all) below.

Optional x-ve-session-cookie request header — browser clients only. Send x-ve-session-cookie: 1 (or true/yes — the same vocabulary as revocable) to ask the server to ALSO deliver the issued token in an HttpOnly, Secure, SameSite=Lax cookie scoped to the site's registrable domain (e.g. fast.io), so it is available across subdomains on that domain and the session never has to be stored anywhere JavaScript can read it between page loads. The token is still returned in the response body as usual. The browser then calls POST /current/user/auth/bootstrap/ on each page load — the only endpoint that reads the cookie — which returns that same token so the app can bring it into memory. The opt-in is only honoured as a request header; it is deliberately not accepted as a URL or body parameter. Omit the header (the default) and no cookie is set. On a 2FA-enabled account, sign-in returns a pre-2FA token and NO cookie; the cookie is issued by POST /current/user/auth/2factor/auth/{token}/ instead.

Method 2: API Keys

Long-lived tokens for service-to-service communication. Created via the API or the web UI. Used with the same Authorization: Bearer {api_key} header format as JWTs. Keys optionally support scoped permissions (scopes), agent names (agent_name), and expiration (expires). Scoped keys are enforced using the same scope system as v2.0 JWT tokens. A key created or updated without scopes now stores the explicit ["user:*:rw"] — whole-account read and write, no administration and no account settings.

Scope formats: OAuth authorization requests accept named scope strings (user, org, workspace, all_orgs, all_workspaces, all_shares). API responses return scopes as arrays of entity_type:entity_id:access_mode strings (e.g., ["org:12345:rw"]) — exactly three colon-separated parts. The entity types are user, org, workspace, share, fileshare, memory and userdetails; the entity id is * (wildcard) or a numeric id. See the OAuth 2.0 reference for full scope format details.

Access modes. The third part of a scope string is one of three modes:

rwa implies rw, which implies r. There is no ra — administration always includes write. rwa is accepted on the ordinary entity types (user, org, workspace, share) but not on fileshare, which has no administrative verb: fileshare:{id}:rwa and any fileshare:* scope are refused when a credential is issued. userdetails is narrower still — the only issuable form is the exact userdetails:*:rw, and userdetails:*:r, userdetails:*:rwa and any numeric id are refused at grant time.

Administration is always capped by the human. rwa never grants more than the person who owns the credential currently holds — it is re-checked on every request against their live role on the entity. If they lose administrative rights on an org or workspace, a credential carrying rwa for it stops administering it.

The user:* grants:

A user:* grant matches every ordinary entity type. It does not match userdetails, which is explicit-only.

The userdetails entity type. userdetails:*:rw is the only valid form — userdetails:*:r, userdetails:*:rwa and any numeric id are refused when a credential is issued. It gates exactly four operations:

• POST /current/user/update/ — changing password or email_address only
• POST /current/user/auth/2factor/{channel}/ — enrolling in 2FA
• POST /current/user/auth/2factor/verify/{token}/ — verifying 2FA enrolment
• POST /current/user/auth/invalidate-all/ — invalidating every session on the account

No user:* grant, at any access mode, satisfies it: it must be held explicitly, or the caller must be an interactive browser login session. It is an entity type inside a credential's scopes list, not a scope type in the OAuth authorization flow, and it is never advertised in scopes_supported.

Credentials with no scopes (“legacy”). A credential is legacy when it declares no scopes claim at all: an API key created before scoped keys existed, an OAuth session minted before scoped tokens existed, and every browser login session. Legacy is therefore not a synonym for “old API key”.

• A legacy API key or legacy OAuth grant behaves as user:*:rw — whole-account read and write, no administration and no account settings. It does not retain unrestricted access.
• A browser login session is different: it is unbounded — admin-capable, and it passes the account-settings gate, because it is the human acting interactively.

Newly issued credentials are never legacy: a key created or updated without scopes stores the explicit ["user:*:rw"], and an OAuth grant for scope=user is stored the same way.

Containment — no credential may mint something broader than itself. A credential may only create or edit another credential whose scopes it already covers. Covering compares access-mode rank (rwa ≥ rw ≥ r), and a wildcard id covers any id of that type while a numeric id covers only itself: org:*:rw covers org:123:r, but org:123:rw does not cover org:*:r. There is no hierarchy walk — org:1:rwa does not cover workspace:5:rw. userdetails:*:rw must be held exactly to be propagated, and an empty scope set is refused everywhere it can be submitted. A browser login session is unbounded and may mint anything the human may grant.

Method 3: OAuth 2.0 PKCE

For desktop/mobile apps and MCP-connected agents. No password passes through the agent. Access tokens last 1 hour; refresh tokens are long-lived. S256 challenge method only. See the OAuth 2.0 reference for the full flow.

Method 4: 2FA

When 2FA is enabled on an account, Basic Auth returns a limited-scope JWT. Complete authentication via POST /current/user/auth/2factor/auth/{token}/ with the 2FA code. The response contains a full-scope JWT.

What the access modes mean for existing credentials

• An existing read-write API key or OAuth grant keeps reading and writing, but no longer performs administrative operations — org, workspace and share administration, including administrative reads such as org billing details, invoices, usage, credits, plan preview and payment method, and the events audit log — and no longer changes account settings (password, email address, 2FA enrolment, invalidate-all).
• To restore administration, update the key with rwa scopes, or reconnect the application asking for access_mode=rwa.
• To restore account settings, add userdetails:*:rw to the key, or reconnect the application with account_settings=1. Widening a credential can only be done from a signed-in web session — a credential cannot widen itself.
• user:*:r is now a real whole-account read-only grant: it returns full read results where it previously returned empty lists on some endpoints.
• Clients validating access_modes_supported against {r, rw} must accept rwa.

Getting Started

Option 1: Use a Human's Existing Account (API Key)

A human creates an API key and gives it to you. You operate as that user with their permissions, org, and billing.

Human instructions: "Go to Settings > Devices & Agents > API Keys and click Create API Key. Optionally enter a memo to label the key (e.g., 'Agent access'), then click Create. Copy the key immediately -- it is only displayed once. Direct link: https://go.fast.io/settings/api-keys"

Once you have the key: Authorization: Bearer {api_key}. No further steps needed.

Option 2: Create Your Own Agent Account (Autonomous)

Create your own account to work independently. Agent accounts are ordinary Fastio accounts tagged account_type=agent — they require an email address and follow the same signup, organization, and paid-plan flow as everyone else.

1. POST /current/user/ with email_address, password, tos_agree=true, agent=true
2. GET /current/user/auth/ with Basic Auth to get JWT
3. Verify email:
   • POST /current/user/email/validate/ with email — sends verification code
   • POST /current/user/email/validate/ with email and email_token — validates the code
4. POST /current/org/create/ with domain (required, 2-63 chars lowercase alphanumeric + hyphens)
5. Select a paid plan to activate the org via POST /current/org/{org_id}/billing/ with billing_plan (e.g. solo_monthly) — a new organization must choose a paid plan (Starter, Business, or Growth) before it can be used (see the Organizations reference)
6. POST /current/org/{org_id}/create/workspace/ with folder_name, name, perm_join, perm_member_manage

New organizations choose a paid plan (Starter, Business, or Growth) to get started; until a paid plan is selected the org is in an upgrade-only state (the same state as an org that has exhausted its credits).

Option 3: Agent Account Invited to a Human's Org

1. Create an agent account (steps 1-2 from Option 2)
2. Give the human your agent's email address
3. Human invites agent to their org or workspace
4. Accept: POST /current/org/{org_id}/members/join/ or POST /current/workspace/{workspace_id}/members/join/
5. You now operate within their resources with granted permissions

Option 4: PKCE Browser Login (No Password Sharing)

Most secure option. Works with SSO. No credentials pass through the agent.

1. Agent initiates PKCE flow via POST /current/oauth/authorize/ with code_challenge, code_challenge_method=S256, client_id, redirect_uri, response_type=code
2. User opens the returned URL in browser, signs in, approves access
3. Browser displays authorization code — user copies it to agent
4. Agent calls POST /current/oauth/token/ with grant_type=authorization_code, code, code_verifier
5. Access tokens last 1 hour; refresh via POST /current/oauth/token/ with grant_type=refresh_token

Which option to choose

• Human wants you to manage their account → Option 1 (API key)
• You're building something independently → Option 2 (agent account + own org)
• You need to work within a human's existing org → Option 3 (agent account + invitation)
• Human wants to authorize agent without sharing credentials → Option 4 (PKCE)

Compact Responses (output=)

Every endpoint that returns user objects — including your own profile (/current/user/details/), other users' profiles, and member listings on workspaces, orgs, and shares — accepts an optional output query parameter that selects the response shape. A single detail-level token may be combined with modifier tokens; specifying two detail levels (e.g. ?output=terse,standard) returns HTTP 406. When output= is omitted, responses are full and byte-for-byte unchanged.

Use terse for mention pickers, avatar lists, creator cells, and message-author headers — it carries the identifier, display name, account type (human/agent), and profile picture, which is everything the avatar/name cells render. email_address is intentionally excluded from terse to keep PII out of the smallest shape. Use standard for member list views and account-settings summaries — it adds email_address, the caller-relative permissions role, active/pending status, invitation details for pending members, and account created/updated timestamps (now visible at standard for every user the caller can see, not just self/managers). Membership responses — the member-detail endpoint for an org, workspace, or share — also carry member_added_at at standard: the date the membership was created, distinct from created, which is the date the user's own account was created. Fastio returns it to the member themselves and to admins (and owners) of the containing org, workspace, or share; for any other caller the key is absent from the response rather than null, and it is omitted for every caller when the membership has no recorded date. It is formatted like every other response timestamp, e.g. 2026-08-26 14:03:11 UTC. Admin member-list UIs also receive the lock/suspend/close account-status chips at standard; these three fields are gated server-side to the self-view or manager-view of the target user, so non-privileged callers never see them at any tier. Use full (or omit the parameter) for the user profile screen, account settings, admin audits, and any workflow that reads phone, 2FA, TOS, anonymous-guest detection, or account-validity fields. Unknown tokens are silently ignored. Add the markdown modifier (e.g. ?output=standard,markdown) to receive the response as GitHub-flavored Markdown (Content-Type: text/markdown; charset=UTF-8) instead of JSON — see the cross-cutting ?output= reference for the full contract.

User Creation

POST /current/user/

Create a new user account.

Auth: None (IP-throttled)

Request Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/" \
  -d "email_address=jane.doe@example.com" \
  -d "password=$PASSWORD" \
  -d "tos_agree=true" \
  -d "first_name=Jane" \
  -d "last_name=Doe" \
  -d "agent=true"

Success Response (200 OK)

{
  "result": true
}

Response Fields

Error Responses

Notes

• Account enumeration is intentionally not possible. Signing up with an email that already has an account does NOT return an "already in use" error — it returns the SAME success response as a brand-new signup and emails the existing account so the owner can sign in / reset their password. A caller cannot use signup to tell whether an email is registered, and no duplicate account is created.
• Email addresses are normalized by stripping tag extensions (e.g., user+tag@example.com becomes user@example.com) for storage and uniqueness lookup; the original email is preserved separately.
• Country code is detected from the client IP and stored automatically.
• agent=true is permanent and cannot be changed after account creation.
• An email address is required for every account, agent or human. The agent=true tag is for identification only and does not grant a different or free plan.

User Management Endpoints

POST /current/user/update/

Update the current authenticated user's profile information.

Auth: Required (JWT)

Request Parameters

All fields are optional. Only provided fields are updated.

Request Example

curl -X POST "https://api.fast.io/current/user/update/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "first_name=Jane" \
  -d "last_name=Smith"

Success Response (200 OK)

{
  "result": true,
  "sessions_invalidated": true,
  "auth_token": "{jwt_token}"
}

Both extra fields are optional and appear only when the password was changed:

If sessions_invalidated is true but no auth_token is returned, you authenticated with a credential that was not invalidated (an API key or an OAuth access token), so no replacement is needed and you can keep using it. Do not treat a missing auth_token as a failure.

Error Responses

Notes

• Order of the credential checks when password or a changed email_address is sent: the credential-breadth gate runs first (10769), then a passwordless account is refused (10766), then the current_password proof (10759). For password, validation of the value (10026) runs before the gates; for email_address, an unchanged address is a no-op that runs none of them, and a changed address passes the gates before it is validated (10025).
• Changing the password or the email requires userdetails:*:rw. Both are account settings, so a request carrying password or a changed email_address is refused with 403 and 10769 unless the credential explicitly holds userdetails:*:rw, or the caller is a browser login session (which passes). user:*:rw, user:*:rwa, every entity-scoped key and every legacy (unscoped) key are all refused — a whole-account grant does not confer account settings. The same bar applies to POST /current/user/auth/2factor/{channel}/, POST /current/user/auth/2factor/verify/{token}/ and POST /current/user/auth/invalidate-all/. This covers setting the initial password on an SSO-only account too. The other fields on this endpoint (names, phone, owner_defined) are not gated.
• Changing an existing password OR email requires the current password. If the account already has a password, a password change or an email_address change must include a valid current_password (POST-only) or it is rejected with 1700/403/10759 — this prevents a session-only attacker (e.g. a stolen JWT) from overwriting the password or hijacking the email. Use the password_set field on GET /current/user/details/ to tell which case applies.
• An account with no password (SSO-only) sets its FIRST password through the email reset flow, not here. A signed-in session alone must not be able to mint a durable credential for the account, so password on a passwordless account is refused with 10766. Call POST /current/user/email/reset/ with the account's email, open the emailed link, and complete POST /current/user/password/{code}/ — that proves ownership of the email and signs every session out (including the current one), after which the user signs in with email and password. The same applies to email_address: a passwordless account cannot change its email on a bare session (the new address would only have to be confirmed by whoever supplied it) — set a password first, then change the email with current_password.
• Changing the email address starts a confirmation flow rather than changing it immediately: a confirmation link is sent to the new address (and a notification to the current address), and the change applies only after the link is confirmed via /current/user/email/change/. The current email remains active and verified until then. When a change is pending, the response includes "email_change_pending": true.
• Changing the password signs out the account's other browsers and devices. Existing sign-in sessions stop working on their next request and must sign in again with the new password. The session that made this request is kept alive by the auth_token returned above — store it and use it in place of the token you sent, or your next call will be rejected too.
• AI assistant sessions are NOT signed out. They are short-lived and delegated, so a routine password change leaves an in-progress assistant session running rather than interrupting it mid-task.
• Not affected: OAuth-connected applications, API keys, guest share access, file-share links and open realtime connections. These are revoked separately — remove the connected application or delete the API key.
• Sessions created before account-wide revocation was introduced do not carry the markers this check relies on, and are therefore refused outright: any such sign-in session is already signed out and must sign in again. Current sign-in sessions, OAuth tokens, API keys and the other credentials listed above are not affected.
• Phone number changes require 2FA to be disabled first.
• If no fields have changed, the endpoint returns success and no update is performed.

POST /current/user/close/

Close (soft-delete) the current user's account.

Auth: Required (JWT)

Request Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/close/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "email_address=jane.doe@example.com"

Success Response (202 Accepted)

{
  "result": true
}

Dry Run Response (Cannot Close, 202 Accepted)

{
  "result": false
}

Error Responses

Notes

• 2FA verification is required if 2FA is enabled on the account.
• Users who own active organizations must close or transfer ownership first.
• The dryrun parameter checks closure eligibility without actually closing the account.
• On closure: subscriptions are cancelled, SSO connections are removed, the account is flagged as closed.

POST /current/user/email/

Deprecated. This endpoint previously reported whether an email was already registered, which let anyone enumerate Fastio accounts. It no longer performs any account lookup: for any well-formed email it returns a uniform 202 Accepted / result: true. It is retained only so existing callers keep receiving a success response. To handle an already-registered email, just call signup (POST /user/) — it notifies the existing account and returns the same success as a new signup.

Auth: None (IP-throttled)

Request Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/email/" \
  -d "email=jane.doe@example.com"

Response (202 Accepted) — always, regardless of whether the email is registered

{
  "result": true
}

Error Responses

Notes

• The response does not reveal whether the email is registered (account enumeration is intentionally not possible).

POST /current/user/email/reset/

Request a password reset email.

Auth: None (IP-throttled)

Request Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/email/reset/" \
  -d "email=jane.doe@example.com"

Success Response (202 Accepted)

{
  "result": true
}

Error Responses

Notes

• For security, this endpoint always returns success regardless of whether the email exists in the system.

POST /current/user/email/validate/

Send or validate an email verification code. Two-step flow.

Auth: Required (JWT)

Mode 1: Send Verification Code

When email_token is NOT provided, sends a new validation code to the user's email.

Mode 2: Validate Code

When email_token IS provided, validates the code and marks the email as verified.

Request Example (Send Code)

curl -X POST "https://api.fast.io/current/user/email/validate/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "email=jane.doe@example.com"

Request Example (Validate Code)

curl -X POST "https://api.fast.io/current/user/email/validate/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "email=jane.doe@example.com" \
  -d "email_token=123456"

Success Response (202 Accepted)

{
  "result": true
}

Side Effects

• On successful validation, any pending invitations addressed to this email remain pending. The user accepts them explicitly via the invitation accept endpoints (list pending invitations with GET /current/user/invitations/list/, then accept with POST /current/user/invitation/{invitation_id}/accept/).

Error Responses

POST /current/user/email/change/

Confirm a pending email change. Consumes the one-time confirmation token from the link that was emailed to the new address when the change was requested via /current/user/update/, and applies the new email.

Auth: Required (JWT). The signed-in user must be the account the change was requested for.

Request Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/email/change/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "token={confirmation_token}"

Success Response (202 Accepted)

{
  "result": true
}

Side Effects

• On success the new email becomes the account email and is marked verified. Any pending invitations addressed to the new email remain pending; the user accepts them explicitly via the invitation accept endpoints (list with GET /current/user/invitations/list/, then accept with POST /current/user/invitation/{invitation_id}/accept/).

Error Responses

Notes

• The confirmation token is single-use and time-limited; once used or expired, request the change again via /current/user/update/.

POST /current/user/password/{code}/

Set a new password using a password reset code.

Auth: None (code-based authentication)

Path Parameters

Request Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/password/abc123def456/" \
  -d "password1=NewSecureP@ss" \
  -d "password2=NewSecureP@ss"

Success Response (202 Accepted)

{
  "result": true
}

Error Responses

Notes

• 10204 is overloaded and the HTTP status is what separates the two meanings. At 406 it is a caller mistake (the two password fields are missing or do not match) and is worth reporting to the user; at 500 it is a server-side failure writing the password, carries a completely different message, and the user did nothing wrong. Branch on the status, not on the code alone. 10203 is only ever the 500.
• The reset code is consumed by an atomic claim immediately before the new password is written, so a replayed or concurrent request carrying the same code is refused with the same error as an unknown code. If the password write itself fails after the claim, the code is already spent and a new reset must be requested.
• Completing a reset signs out the account's other browsers and devices. Any existing sign-in session stops working on its next request. This endpoint does not return a token — sign in normally with the new password afterwards to obtain one. OAuth-connected applications, guest share access and open realtime connections are not affected; revoke those separately.

GET /current/user/password/{code}/details/

Get details of a password reset code (check if valid/expired).

Auth: None (code-based)

Path Parameters

Request Example

curl -X GET "https://api.fast.io/current/user/password/abc123def456/details/"

Success Response (200 OK)

{
  "result": true,
  "email": "jane.doe@example.com"
}

Response Fields

Error Responses

GET /current/user/phone/{country_code}-{phone_number}/

Validate a phone number and country code combination.

Auth: Required (JWT)

Path Parameters

Request Example

curl -X GET "https://api.fast.io/current/user/phone/1-5551234567/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (202 Accepted)

{
  "result": true
}

Error Responses

GET /current/user/pin/

Get the user's support PIN and identity verification hash.

Auth: Required (JWT)

Request Example

curl -X GET "https://api.fast.io/current/user/pin/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "supportcode": "1234",
  "intercom": "a1b2c3d4e5f6..."
}

Response Fields

Error Responses

GET|POST /current/user/sso/signin/{provider}/

SSO (Single Sign-On) authentication flow.

Auth: None (IP-throttled)

Path Parameters

GET: Get SSO Redirect URL

Returns the OAuth2 authorization URL for the specified provider.

curl -X GET "https://api.fast.io/current/user/sso/signin/google/"

To request a session-bound JWT after the SSO flow completes:

curl -X GET "https://api.fast.io/current/user/sso/signin/google/?revocable=true"

Optional Query Parameters (GET only)

GET Response (200 OK)

{
  "result": true,
  "provider": "google",
  "redirect_url": "https://accounts.google.com/o/oauth2/v2/auth?response_type=code&client_id=...",
  "return_url": "https://fast.io/sso/callback/google"
}

Response Fields

POST: Process SSO Callback

Processes the OAuth2 callback with the authorization code from the provider.

POST Response (200 OK)

{
  "result": true,
  "provider": "google",
  "email": "user@example.com",
  "token": "{jwt_token}",
  "2factor": false,
  "account_created": true
}

Response Fields

Error Responses

Notes

• Supported providers: google, microsoft. Requesting any other provider — including apple — is rejected with the 10226 "An unknown provider name was supplied." error.
• GET generates a state token (requires cookies) and returns the redirect URL.
• POST exchanges the authorization code for tokens and creates/links the user account.
• Telling a first-time signup from a returning sign-in: the POST response carries account_created: true only when that exchange created the account. It is omitted for every returning sign-in, so a missing field means "existing account" — use it to send a brand-new user into org creation rather than the normal post-login landing.
• Browser session cookie: send the x-ve-session-cookie header on the POST callback request to also receive the issued token in an HttpOnly cookie, exactly as on GET /current/user/auth/. Because only code the page itself runs can set a header, the opt-in takes effect when the app makes the callback request; where the identity provider posts the browser to the callback directly, no cookie is issued and the app uses the token in the response body as it does today.

GET /current/user/assets/

List available user asset metadata types (e.g., profile photo specifications).

Auth: None

Request Example

curl -X GET "https://api.fast.io/current/user/assets/"

Notes

• Returns the schema/specifications for available asset types, not actual assets.

GET /current/user/available_profiles/

Check what profile types (orgs, workspaces, shares) the current user has access to.

Auth: Required (JWT)

Request Example

curl -X GET "https://api.fast.io/current/user/available_profiles/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "has_orgs": true,
  "has_workspaces": true,
  "has_shares": false,
  "has_pending_invitations": false
}

Response Fields

Error Responses

GET /current/user/{user_id}/details/

Get user profile details.

Auth: Required (JWT)

Path Parameters

Request Example

curl -X GET "https://api.fast.io/current/user/1234567890123456789/details/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "user": {
    "id": "1234567890123456789",
    "account_type": "human",
    "email_address": "jane.doe@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "locked": false,
    "profile_pic": "https://assets.fast.io/..."
  }
}

Response Fields

Self-Only Fields (included only when viewing your own profile)

Error Responses

GET /current/user/me/autosync/{state}/

Enable or disable profile photo auto-synchronization from SSO providers.

Auth: Required (JWT)

Path Parameters

Request Example

curl -X GET "https://api.fast.io/current/user/me/autosync/enable/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true
}

Error Responses

GET /current/user/me/allowed/

Check if the user's country (based on IP geolocation) allows creating shares or organizations.

Auth: None (IP-throttled)

Request Example

curl -X GET "https://api.fast.io/current/user/me/allowed/"

Success Response (200 OK)

{
  "result": true,
  "allowed": true
}

Response Fields

GET /current/user/me/limits/orgs/

Check free organization creation eligibility.

Auth: Required (JWT)

Request Example

curl -X GET "https://api.fast.io/current/user/me/limits/orgs/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "can_create_free_org": false,
  "existing_free_orgs": 0,
  "cooldown_remaining": 0,
  "max_free_orgs": 1,
  "reason": "The free plan is no longer available. Please choose a paid plan.",
  "free_trial_eligible": true,
  "trial_days": 14
}

The free plan is retired for new organizations, so can_create_free_org is false and a reason is returned. (These field NAMES are unchanged. The plan identifier itself is now reported as unpaid rather than free — an organization with no active subscription is on the unpaid tier.) New organizations select a paid plan (Starter, Business, or Growth) instead. While the free plan is closed, existing_free_orgs and cooldown_remaining are not meaningful (reported as 0/null).

The free_trial_eligible and trial_days fields describe whether a NEW org this user creates can start a free trial of a paid plan (vs. buying immediately). A free trial is only available on a user's first organization, so at this pre-org stage free_trial_eligible is true only when the user owns no organization at all — once the user owns (or has ever owned) any organization, every later org is permanently ineligible regardless of elapsed time. A secondary per-user cooldown (60 days on modern plans, anchored at trial start) also applies on top of this. Use these fields to render the plan-selection cards ("Start N-day free trial" vs. "Buy now") before any org exists. When free_trial_eligible is false, a no_trial_reason string is also returned explaining why; a trial_available_at timestamp is included only when the block is the cooldown (the first-org block is permanent, so it has no future date).

Response Fields

Error Responses

GET /current/user/me/list/shares/

List all shares accessible to the current user.

Auth: Required (JWT)

Query Parameters

Request Example

curl -X GET "https://api.fast.io/current/user/me/list/shares/?limit=50&offset=0" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "shares": [
    {
      "id": "1234567890123456789",
      "name": "Project Files",
      "type": "send",
      "archived": false
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

Response Fields

Notes

• This endpoint is paginated. The shares array is a single page (default 100 items). Keep advancing offset by limit while pagination.has_more is true to retrieve every share — reading only the first page will silently miss shares beyond the page size.
• Shares are gathered from three sources: owned by the user, invited to, and joined.
• Duplicates are removed by share ID.
• Does NOT include shares from workspaces the user has access to — only shares with direct user relationships.

GET /current/user/{user_id}/assets/

List set assets (e.g., profile photo) for a user.

Auth: Required (JWT)

Path Parameters

Request Example

curl -X GET "https://api.fast.io/current/user/1234567890123456789/assets/" \
  -H "Authorization: Bearer {jwt_token}"

POST|DELETE /current/user/{user_id}/assets/{asset_name}/

Upload or delete a user asset.

Auth: Required (JWT)

Path Parameters

POST: Upload Asset

Multipart form data with exactly one file upload.

DELETE: Delete Asset

No request body required.

Error Responses

Notes

• Only the user themselves can modify their own assets.
• Uploading or deleting disables profile photo auto-sync.

GET|HEAD /current/user/{user_id}/assets/{asset_name}/read/

Read the binary content of a user asset.

Auth: Required (JWT)

Path Parameters

Notes

• Returns raw binary bytes with appropriate content-type headers, not JSON.
• HEAD returns headers only.

Installed Apps

Track the desktop/mobile apps and agents a user has installed on their account. All four endpoints are user-authenticated and scoped to the calling user; installations are keyed by a caller-defined app_id.

An installation object has this shape everywhere it is returned:

GET /current/user/apps/

List all app installations for the authenticated user (both installed and previously uninstalled).

Auth: Required (JWT)

Request Example

curl -X GET "https://api.fast.io/current/user/apps/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "apps": [
    {
      "id": "1234567890123456789",
      "app_id": "com.example.desktop",
      "app_version": "1.4.2",
      "platform": "macos",
      "status": "installed",
      "installed_at": "2026-07-07 16:37:29 UTC",
      "uninstalled_at": null,
      "last_heartbeat": "2026-07-07 18:02:10 UTC",
      "metadata": null
    }
  ]
}

Response Fields

Error Responses

Notes

• Also responds to HEAD (headers only).

POST /current/user/apps/install/

Register an app installation for the authenticated user. Creates a new record, reinstalls a previously uninstalled app, or updates the version/platform (and refreshes the heartbeat) on an existing installation — all keyed by app_id.

Auth: Required (JWT)

Request Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/apps/install/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "app_id=com.example.desktop" \
  -d "app_version=1.4.2" \
  -d "platform=macos"

Success Response (200 OK)

{
  "result": true,
  "installation": {
    "id": "1234567890123456789",
    "app_id": "com.example.desktop",
    "app_version": "1.4.2",
    "platform": "macos",
    "status": "installed",
    "installed_at": "2026-07-07 16:37:29 UTC",
    "uninstalled_at": null,
    "last_heartbeat": "2026-07-07 16:37:29 UTC",
    "metadata": null
  }
}

Response Fields

Error Responses

Notes

• Idempotent per app_id: calling install again for an already-installed app updates version/platform (when provided) and refreshes last_heartbeat rather than creating a duplicate.
• Calling install for a previously uninstalled app_id reinstalls it (status returns to installed).
• Throttled per user.

POST /current/user/apps/uninstall/

Mark an app installation as uninstalled.

Auth: Required (JWT)

Request Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/apps/uninstall/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "app_id=com.example.desktop"

Success Response (200 OK)

{
  "result": true,
  "installation": {
    "id": "1234567890123456789",
    "app_id": "com.example.desktop",
    "app_version": "1.4.2",
    "platform": "macos",
    "status": "uninstalled",
    "installed_at": "2026-07-07 16:37:29 UTC",
    "uninstalled_at": "2026-07-07 19:15:44 UTC",
    "last_heartbeat": "2026-07-07 18:02:10 UTC",
    "metadata": null
  }
}

Response Fields

Error Responses

POST /current/user/apps/heartbeat/

Record a periodic liveness check-in from an installed app, updating last_heartbeat and optionally the app version.

Auth: Required (JWT)

Request Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/apps/heartbeat/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "app_id=com.example.desktop" \
  -d "app_version=1.4.3"

Success Response (200 OK)

{
  "result": true,
  "installation": {
    "id": "1234567890123456789",
    "app_id": "com.example.desktop",
    "app_version": "1.4.3",
    "platform": "macos",
    "status": "installed",
    "installed_at": "2026-07-07 16:37:29 UTC",
    "uninstalled_at": null,
    "last_heartbeat": "2026-07-07 20:41:03 UTC",
    "metadata": null
  }
}

Response Fields

Error Responses

Notes

• Only currently-installed apps can heartbeat; reinstall via POST /current/user/apps/install/ first if the app was uninstalled.
• Throttled per user.

Invitations

GET /current/user/invitation/{invitation_id}/details/

Get details for a specific invitation.

Auth: Required (JWT)

Path Parameters

Request Example

curl -X GET "https://api.fast.io/current/user/invitation/1234567890123456789/details/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "invitation": {
    "id": "1234567890123456789",
    "invitation_key": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6abcd",
    "inviter": "Jane Doe",
    "invitee_email": "newuser@example.com",
    "entity_type": "workspace",
    "workspace": {
      "id": "9876543210987654321",
      "name": "Marketing Team"
    },
    "state": "pending",
    "created": "2025-01-15 10:30:00 UTC",
    "expires": "2025-01-22 10:30:00 UTC"
  },
  "owner": {
    "id": "1111111111111111111",
    "account_type": "human",
    "email_address": "admin@example.com",
    "first_name": "Admin",
    "last_name": "User",
    "profile_pic": "https://assets.fast.io/..."
  },
  "org": {
    "id": "2222222222222222222",
    "name": "Example Org"
  }
}

Response Fields

Error Responses

Notes

• invitation_key is included because this is the invitee's own authenticated view. It can be used with the per-entity join endpoints (POST /current/{org|workspace|share}/{entity_id}/members/join/{invitation_key}/{accept|decline}/), but prefer the by-id accept/decline endpoints below, which do not require the key.

GET /current/user/invitation/{invitation_id}/public/details/

Get public details for an invitation without authentication.

Auth: None (IP-throttled)

Path Parameters

Request Example

curl -X GET "https://api.fast.io/current/user/invitation/1234567890123456789/public/details/"

Success Response (200 OK)

{
  "result": true,
  "invitation": {
    "id": "1234567890123456789",
    "state": "pending"
  },
  "owner": {
    "id": "1111111111111111111",
    "account_type": "human",
    "first_name": "Admin",
    "last_name": "User"
  },
  "org": {
    "id": "2222222222222222222",
    "name": "Example Org"
  }
}

Notes

• Returns a more limited view than the authenticated version.
• If the profile or owner cannot be loaded, owner will be null.
• The secret invitation_key is never included in this unauthenticated view.

POST /current/user/invitation/{invitation_id}/accept/

Accept a single pending invitation by its ID. Self-service: authorized by the authenticated invitee's verified email (or user ID), so the secret invitation key is not required. Use this to act on the invitations returned by GET /current/user/invitations/list/ — for example from a no-org landing page where the user has no email-link token.

Auth: Required (JWT, validated email)

Path Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/invitation/1234567890123456789/accept/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "invitation": {
    "id": "1234567890123456789",
    "inviter": "Jane Doe",
    "invitee_email": "newuser@example.com",
    "entity_type": "workspace",
    "workspace": {
      "id": "9876543210987654321",
      "name": "Marketing Team"
    },
    "state": "accepted",
    "created": "2025-01-15 10:30:00 UTC",
    "expires": "2025-01-22 10:30:00 UTC"
  }
}

Response Fields

Error Responses

Notes

• Requires a validated email; ownership is verified by matching the authenticated user's verified email (or user ID) to the invitation's invitee.
• On success the user is added as a member of the invitation's entity (org, workspace, or share).
• Idempotent: re-accepting an invitation you have already accepted returns success.

POST /current/user/invitation/{invitation_id}/decline/

Decline a single pending invitation by its ID. Self-service counterpart to the accept endpoint; authorized by the authenticated invitee's verified email (or user ID), no invitation key required.

Auth: Required (JWT, validated email)

Path Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/invitation/1234567890123456789/decline/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "invitation": {
    "id": "1234567890123456789",
    "inviter": "Jane Doe",
    "invitee_email": "newuser@example.com",
    "entity_type": "workspace",
    "workspace": {
      "id": "9876543210987654321",
      "name": "Marketing Team"
    },
    "state": "declined",
    "created": "2025-01-15 10:30:00 UTC",
    "expires": "2025-01-22 10:30:00 UTC"
  }
}

Response Fields

Error Responses

Notes

• A declined invitation is marked declined and no longer appears in GET /current/user/invitations/list/; it will not reappear.
• No membership is created. Idempotent: re-declining an already-declined (or expired) invitation returns success.

POST /current/user/invitations/acceptall/

Accept all pending invitations.

Auth: Required (JWT)

Request Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/invitations/acceptall/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true
}

Notes

• If email is validated, all pending invitations matching that email are accepted.
• If email is not validated, use invitation_key to identify invitations.

GET /current/user/invitations/list/

List all pending invitations for the current user.

Auth: Required (JWT)

Query Parameters

Request Example

curl -X GET "https://api.fast.io/current/user/invitations/list/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "invitations": [
    {
      "id": "1234567890123456789",
      "invitation_key": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6abcd",
      "inviter": "Jane Doe",
      "invitee_email": "newuser@example.com",
      "entity_type": "workspace",
      "workspace": {
        "id": "9876543210987654321",
        "name": "Marketing Team"
      },
      "state": "pending",
      "created": "2025-01-15 10:30:00 UTC",
      "expires": "2025-01-22 10:30:00 UTC"
    }
  ]
}

Response Fields

Notes

• Returns only pending invitations for the current user.
• Each invitation embeds its entity_type and the entity object (org/workspace/share) so cards can render without an extra details fetch.
• invitation_key is included for the invitee's own list. Prefer acting on invitations with the by-id POST /current/user/invitation/{invitation_id}/{accept|decline}/ endpoints, which do not require the key.

User Authentication Endpoints

GET /current/user/auth/

Authenticate via HTTP Basic Auth. Returns JWT token.

Auth: HTTP Basic Auth (email:password)

Query Parameters

Request Headers

Request Example

curl -X GET "https://api.fast.io/current/user/auth/" \
  -u "jane.doe@example.com:$PASSWORD"

To request a revocable session-bound JWT (recommended for browser logins):

curl -X GET "https://api.fast.io/current/user/auth/?revocable=true" \
  -u "jane.doe@example.com:$PASSWORD"

To additionally receive the token in an HttpOnly session cookie (browser logins that keep the token out of client storage):

curl -X GET "https://api.fast.io/current/user/auth/" \
  -u "jane.doe@example.com:$PASSWORD" \
  -H "x-ve-session-cookie: 1" \
  --cookie-jar cookies.txt

Success Response (200 OK)

{
  "result": true,
  "expires_in": 86400,
  "auth_token": "{jwt_token}",
  "2factor": false
}

Response Fields

Error Responses

Notes

• Email tags (e.g., user+tag@example.com) are stripped before lookup.
• If 2FA is enabled, complete the 2FA verification flow to upgrade the token.
• A failed sign-in reports how many attempts remain. The 401 response carries error.params.attempts_remaining — the number of further failures this account tolerates before it is temporarily locked — alongside error.params.attempts_max, the threshold in force, so a client can render "2 of 5" without hard-coding a limit that can change. Both fields are absent when the count is unknown (it could not be recorded); treat absence as "unknown" and show a plain invalid-credentials message rather than assuming zero. The value carries no account-existence signal: the counter is keyed on the submitted address, so an unregistered email reports the same countdown as a registered one.
• Repeated failed sign-in attempts temporarily lock the account. After too many consecutive failures this endpoint returns 429 with error.code 10760, and the response body carries error.params.retry_after_seconds — the number of seconds until sign-in is accepted again. Wait that long before retrying; further attempts during the lockout do not extend it, but they do not succeed either. A successful sign-in clears the failure count.
  • Do not confuse this with "Your account is locked" (401). That one is an administrative lock a client cannot wait out and requires contacting support; 10760 clears by itself.
  • Do not confuse it with the per-IP rate limit, which also returns 429 but with error.code 10368 and reflects request volume from your address rather than failed credentials for one account.
  • Clients should not retry sign-in automatically on a 429; an automatic retry consumes the account's remaining attempts without user intervention.
• Account enumeration is intentionally not possible: an unknown email, an SSO-only account (no password), and a wrong password all return the identical 401/error.code 10008/"Your credentials supplied are invalid." response with matched timing. SSO-only accounts must sign in via their provider instead.
• Pass revocable=true to mint a session-bound JWT that respects sign-out. The default (omitted) yields a stateless JWT that cannot be invalidated server-side and is appropriate for service-to-service tokens, AI tokens, and any non-browser caller.
• The x-ve-session-cookie header additionally delivers the token as an HttpOnly cookie. It is opt-in per request: omit it — which is what every non-browser client does — and the response and behaviour are unchanged in every respect. The cookie carries the SAME token as auth_token, not a second credential, and expires when that token does. The opt-in is only honoured as a request header; sending it in the query string or the body does nothing.
• A 2FA-enabled account gets no cookie from this call. Sign-in returns a pre-2FA token ("2factor": true), which is not a completed session and is never put in a cookie. Send x-ve-session-cookie again on POST /current/user/auth/2factor/auth/{token}/; that call issues the cookie.

POST /current/user/auth/bootstrap/

Return the session token held in the browser's HttpOnly cookie. A browser that signed in with the x-ve-session-cookie header calls this on page load to bring that token into memory, then uses it in the Authorization header for every other request.

This is the ONLY endpoint in the API that authenticates from a cookie — every other endpoint still requires Authorization: Bearer {token}, unchanged. The point of the arrangement is that the durable session credential never has to live anywhere JavaScript can read it, except in memory once bootstrap hands it back.

Auth: The HttpOnly session cookie ONLY, sent automatically by the browser. A request that carries an Authorization header instead is rejected with 401 — a caller that already holds a token does not need to bootstrap.

Rate Limited: Yes (per user)

Request Parameters: None.

Request Example

curl -X POST "https://api.fast.io/current/user/auth/bootstrap/" \
  --cookie cookies.txt

Success Response (200 OK)

{
  "result": true,
  "id": "1234567890123456789",
  "auth_token": "{jwt_token}",
  "expires_in": 2591990
}

Response Fields

Error Responses

Notes

• This returns the cookie's own token — nothing is minted. auth_token is the same credential the cookie is already holding, and expires_in reports that credential's own remaining life, not a separate short-lived window.
• Call it once per page load. Since bootstrap hands back the existing token rather than issuing a new one, there is no obligation to call it again before that token expires — bring it into memory once per page load, and call it again after a 401 if you need to confirm whether the underlying session is still valid.
• POST only. A GET returns the standard 405 Method Not Allowed. POST is required because SameSite=Lax still sends cookies on cross-site top-level GET navigations, and this response body contains a bearer token.
• Call it same-origin from whatever page is making the request. The cookie is scoped to the site's registrable domain (e.g. fast.io) rather than a single host, so it travels to every subdomain on that domain — including one different from wherever sign-in happened. The API still sends Access-Control-Allow-Origin: * and never Access-Control-Allow-Credentials, so a browser will not expose this response to a script running on a different origin than the one that made the request.
• Nothing else about the API changes: after bootstrapping, send Authorization: Bearer {auth_token} on every other call exactly as before.
• Rate limited per user. A browser legitimately calls this once per page load and once per restored tab.
• The cookie only exists if the client opted in with the x-ve-session-cookie header at sign-in — or, on a 2FA-enabled account, at 2FA completion. Without it there is nothing to bootstrap.
• POST /current/user/auth/sign-out/ clears the cookie, so a signed-out browser gets the 401 above on its next bootstrap.

POST /current/user/auth/sign-out/

Invalidate every revocable JWT issued to the calling user. The user's session counter is incremented; revocable tokens carrying the previous counter value will be rejected on their next request.

Auth: Required (JWT, scope: user or admin; or an unscoped API key for the user)

This is account-wide, not session-scoped. It bumps the user's SHARED session counter, so it signs out every revocable session on the account — not only the caller's. An entity-scoped API key is therefore refused with 10175, the same bar invalidate-all/ applies: a key carries no sv claim, so a sign-out never affects the key itself, which makes this purely an action on other people's sessions when called with one. An unscoped key is unaffected. To end only your own session, discard your own credential — this endpoint cannot do that selectively.

Rate Limited: Yes (per user)

Request Example

curl -X POST "https://api.fast.io/current/user/auth/sign-out/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true
}

Notes

• Only affects JWTs minted with revocable=true on GET /current/user/auth/. API keys, OAuth/PKCE access tokens, agent tokens, and JWTs minted without revocable are not session-bound and are unaffected.
• The bump applies to all revocable tokens for this user across every browser and device. There is no per-device sign-out via this endpoint.
• The HttpOnly session cookie IS cleared by this call. A browser that opted into it with the x-ve-session-cookie header loses it here, so its next POST /current/user/auth/bootstrap/ returns 401 instead of silently signing it back in. Nothing else the client stored is cleared — the client remains responsible for the rest of its local credential state after sign-out.
• To terminate ALL of a user's sessions — including logins that did NOT opt into revocable — use POST /current/user/auth/invalidate-all/ below instead.

POST /current/user/auth/invalidate-all/

Invalidate EVERY login session for the calling user — a strict superset of sign-out. Kills interactive logins (browser, 2FA, password-reset, SSO) regardless of whether they opted into revocable. Any token issued before this call is rejected on its next request.

Use this for "sign me out of all devices" or a suspected account compromise — i.e. account-security actions, as opposed to a per-browser logout button (use sign-out for that). A password change or reset already invalidates other sessions on its own, so calling this afterwards is unnecessary and will additionally invalidate the replacement auth_token that the password change just returned, signing you out of the session you are using. Call it after a password change only when you deliberately want every session gone, including your own.

Auth: Required (a browser login session, or a credential explicitly holding userdetails:*:rw — see the gate below)

This is a strict superset of sign-out/, not a different class of action — both bump the user's shared session counters and both reach every session on the account; this one additionally kills tokens carrying gsv.

This is an account-settings operation and requires userdetails:*:rw. A credential that does not explicitly hold that scope is refused with 403 and 10769 (error.params.reason: userdetails_scope_required). user:*:rw, user:*:rwa, entity-scoped keys and legacy (unscoped) keys are all refused; a browser login session passes. The limited twofactor-scope token from a half-completed 2FA sign-in is refused separately with 10175. POST /current/user/auth/sign-out/ is not gated this way.

Request Example

curl -X POST "https://api.fast.io/current/user/auth/invalidate-all/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true
}

Notes

• Kills interactive logins (browser, 2FA, password-reset, SSO) whether or not they opted into revocable. Enforcement is opt-in per token, so tokens that never carried the marker — OAuth/PKCE access tokens, anonymous share-guest tokens, AI assistant sessions, short-lived realtime/websocket and FileShare resource tokens, and API keys — are NOT affected and keep their own revocation paths (revoke the OAuth grant, delete the API key, etc.).
• Anonymous share-guest sessions and suspended/locked/closed/abuse-flagged accounts are rejected (nothing to invalidate / already terminated).
• It does NOT clear client-side storage, and — unlike sign-out — it does not clear the HttpOnly session cookie either. The client must clear its own credential state and re-authenticate afterward.
• Rate limited per user.
• A platform-wide “log everyone out” also exists: all tokens can be invalidated platform-wide by a Fastio operator action. It has no API.

GET /current/user/auth/check/

Validate current JWT and get user ID.

Auth: Required (Bearer token)

Request Example

curl -X GET "https://api.fast.io/current/user/auth/check/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "id": "1234567890123456789"
}

Response Fields

Notes

• Lightweight health-check for token validity. Only validates that the JWT is structurally valid and not expired.

GET /current/auth/scopes/

Token scope introspection. Returns information about the current token's scope, auth type, and agent status.

Auth: Required (Bearer token)

Request Example

curl -X GET "https://api.fast.io/current/auth/scopes/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "auth_type": "jwt_v2",
  "scopes": ["org:12345:rw", "org:67890:rw"],
  "scopes_detail": [],
  "is_agent": true,
  "agent_name": "My MCP Agent",
  "full_access": false,
  "admin": false,
  "legacy": false
}

Response Fields

How the flags combine

Error Response (401 Unauthorized) — the token could not be verified

{
  "result": false,
  "error": {
    "code": 154843,
    "text": "The supplied token could not be verified.",
    "params": { "reason": "verification_failed" }
  }
}

A bearer token that cannot be decoded returns 401 with error.params.reason set to verification_failed. This is never answered with a 200. Treat it as "this token was not checked", NOT as "this token has no rights" — a successful response always describes a token that was read; it never reports the absence of scopes because verification failed.

reason carries a single value here on purpose. The underlying cause — an expired credential, a forged or malformed one, or key material being temporarily unavailable — is not distinguishable at this layer, and reporting a guessed cause would be worse than reporting that it is unknown. Branch on reason, never on error.code (the numeric code identifies the call site and is not a stable contract).

API Keys

POST /current/user/auth/key/

Create a new API key.

Auth: Required (JWT, scope: user or admin)

Request Parameters

scopes handling

The same rules apply to creating a key and to updating one (POST /current/user/auth/key/{key_id}/):

An unscoped key is never created any more. The explicit ["user:*:rw"] is stored instead, which is the same authority a legacy key has: whole-account read and write, no administration, no account settings.

Issuance checks (create and update)

They run in this order on the final effective scope set:

1. Empty set → 406 190363 — "The scopes provided must contain at least one scope."
2. Broader than the calling credential → 403 10768, error.params.reason scope_exceeds_issuer — "The requested scopes are broader than the credential making this request." A browser login session skips this check; it is unbounded.
3. Not grantable to this user → 406 185003 — the human does not hold the entity, or the scope string is not issuable at all (for example userdetails:*:rwa or fileshare:*:rw).

Request Example

curl -X POST "https://api.fast.io/current/user/auth/key/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "memo=CI/CD Pipeline Key"

Request Example (scoped key with expiration)

curl -X POST "https://api.fast.io/current/user/auth/key/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d "memo=Workspace Agent" \
  -d 'scopes=["workspace:1234567890123456789:rw"]' \
  -d "agent_name=my-agent" \
  -d "expires=2026-12-31 23:59:59 UTC"

Success Response (200 OK)

{
  "result": true,
  "api_key": "{the raw key, shown only here}",
  "key": {
    "id": "{key_id}",
    "memo": "Workspace Agent",
    "scopes": "[\"workspace:1234567890123456789:rw\"]",
    "agent_name": "my-agent",
    "created": "2026-09-09 14:03:11 UTC",
    "expires": "2026-12-31 23:59:59 UTC",
    "admin": false,
    "legacy": false,
    "api_key": "****************************abcd"
  }
}

Response Fields

api_key is the secret. key is the created row, in the same shape the read and update calls return — including its own masked api_key. The two are siblings so that reading the secret stays exactly as simple as it was.

key is a new field and the addition is backwards compatible: api_key is unchanged and still the raw string. Use key when you need the new key's id, created or expires without a second call.

key is best effort. It is built by reading the stored row back, and on the rare occasion that read fails the response is {"result": true, "api_key": "…"} with no key field — the key is created and the secret is still returned, because losing the one-time secret to a failed convenience lookup would be the worse outcome. Treat key as optional. If it is absent and you need the row, list your keys with GET /current/user/auth/keys/ and match on created — the degraded response carries the secret only, so there is no id in it to read back by.

Error Responses

Notes

• 2FA verification is required if 2FA is enabled.
• The full key value is only returned at creation time, as the top-level api_key string. Subsequent reads return masked versions. The admin and legacy flags appear on the key object create returns as well as on GET, POST (update) and the list endpoint.
• A key can never be minted broader than the credential minting it (see the issuance checks above). Widening therefore has to be done from a signed-in web session.

GET /current/user/auth/key/{key_id}/

Get details of an API key (key value is masked).

Auth: Required (JWT, scope: user or admin)

Scope visibility. A write-capable account-wide credential (user:*:rw or user:*:rwa), a legacy key, and a signed-in web session see every key on the account. Every other credential — one created with entity scopes, and also user:*:r — sees only the keys its own grant contains — the same containment rule POST /current/user/auth/key/ applies to a mint. A key outside that grant is not visible and answers 403 10175, exactly as before. This is what lets a scoped agent inspect and revoke the keys it creates; it never widens what a credential can reach.

Path Parameters

Request Example

curl -X GET "https://api.fast.io/current/user/auth/key/key_12345/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "api_key": {
    "id": "key_12345",
    "api_key": "****************************ab12",
    "memo": "CI/CD Pipeline Key",
    "created": "2024-01-15 10:30:00 UTC",
    "scopes": "[\"workspace:1234567890123456789:rw\"]",
    "agent_name": "my-agent",
    "expires": "2026-12-31 23:59:59 UTC",
    "admin": false,
    "legacy": false
  }
}

Response Fields

Error Responses

POST /current/user/auth/key/{key_id}/

Update an existing API key's memo, scopes, agent_name, and/or expires.

Auth: Required (JWT, scope: user or admin)

The update verb is POST. There is no PUT on this path.

Containment is re-checked on every update, including a metadata-only edit such as changing expires or memo: the key's stored scopes are the effective set being re-authorized, so they must still be covered by the credential making the request. A request that would leave the key broader than its issuer is refused with 403 and 10768 (error.params.reason: scope_exceeds_issuer). A browser login session is unbounded and skips that check.

Path Parameters

Request Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/auth/key/key_12345/" \
  -H "Authorization: Bearer {jwt_token}" \
  -d 'scopes=["org:1234567890123456789:r"]' \
  -d "agent_name=updated-agent"

Success Response (200 OK)

{
  "result": true,
  "api_key": {
    "id": "key_12345",
    "api_key": "****************************ab12",
    "memo": "CI/CD Pipeline Key",
    "created": "2024-01-15 10:30:00 UTC",
    "scopes": "[\"org:1234567890123456789:r\"]",
    "agent_name": "updated-agent",
    "expires": null,
    "admin": false,
    "legacy": false
  }
}

Error Responses

Notes

• Only the fields you send are updated; omitted fields remain unchanged.
• Send empty string or "null" to clear a nullable field. Clearing scopes restores the explicit ["user:*:rw"], not an unscoped key.
• The response object carries the admin and legacy booleans described under GET /current/user/auth/key/{key_id}/.
• 2FA verification is required if 2FA is enabled.
• The update path is taken only when {key_id} is a well-formed key identifier. If {key_id} is not a valid key-ID, the request is NOT rejected — it falls through to the create path (see POST /current/user/auth/key/) and mints a brand-new key. Always confirm the {key_id} you send is valid before treating a call as an update.

DELETE /current/user/auth/key/{key_id}/

Delete an API key.

Auth: Required (JWT, scope: user or admin)

Scope visibility. A write-capable account-wide credential (user:*:rw or user:*:rwa), a legacy key, and a signed-in web session see every key on the account. Every other credential — one created with entity scopes, and also user:*:r — sees only the keys its own grant contains — the same containment rule POST /current/user/auth/key/ applies to a mint. A key outside that grant is not visible and answers 403 10175, exactly as before. This is what lets a scoped agent inspect and revoke the keys it creates; it never widens what a credential can reach.

Path Parameters

Request Example

curl -X DELETE "https://api.fast.io/current/user/auth/key/key_12345/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true
}

Error Responses

Notes

• 2FA verification is required if 2FA is enabled.
• Returns "not found" if the key belongs to a different user (does not reveal ownership).

GET /current/user/auth/keys/

List all API keys for the user.

Auth: Required (JWT, scope: user or admin)

Scope visibility. A write-capable account-wide credential (user:*:rw or user:*:rwa), a legacy key and a signed-in web session list every key on the account. Every other credential — one created with entity scopes, and also user:*:r — lists only the keys its own grant contains — the same containment rule POST /current/user/auth/key/ applies to a mint. Keys outside that grant are omitted from api_keys and are not counted in results; a narrowed credential that owns no such key receives results: 0 and api_keys: null, the same answer an account with no keys receives.

This is what lets a scoped agent enumerate and revoke the keys it creates. It never widens what a credential can reach: a key it could not have minted stays invisible, and a credential whose scopes cannot be read at all is still refused outright with 403 10175.

Request Example

curl -X GET "https://api.fast.io/current/user/auth/keys/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "results": 2,
  "api_keys": [
    {
      "id": "key_12345",
      "api_key": "****************************ab12",
      "memo": "CI/CD Pipeline Key",
      "created": "2024-01-15 10:30:00 UTC",
      "scopes": "[\"workspace:1234567890123456789:rw\"]",
      "agent_name": "my-agent",
      "expires": "2026-12-31 23:59:59 UTC",
      "admin": false,
      "legacy": false
    },
    {
      "id": "key_67890",
      "api_key": "****************************cd34",
      "memo": "Backup Script",
      "created": "2024-02-20 14:00:00 UTC",
      "scopes": null,
      "agent_name": null,
      "expires": null,
      "admin": false,
      "legacy": true
    }
  ]
}

No Keys Response (200 OK)

{
  "result": true,
  "results": 0,
  "api_keys": null
}

Response Fields

Two-Factor Authentication (2FA)

GET /current/user/auth/2factor/

Get current 2FA status.

Auth: Required (JWT, scope: user or admin)

Request Example

curl -X GET "https://api.fast.io/current/user/auth/2factor/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "state": "enabled",
  "totp": false
}

Response Fields

POST /current/user/auth/2factor/{channel}/

Enable 2FA on the account.

Auth: Required (JWT, scope: user or admin)

Enrolling in 2FA is an account-settings operation and requires userdetails:*:rw. A credential that does not explicitly hold that scope is refused with 403 and 10769 (error.params.reason: userdetails_scope_required) — user:*:rw, user:*:rwa, entity-scoped keys and legacy (unscoped) keys alike. A browser login session passes. The 2FA login challenge endpoints are not gated this way.

Path Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/auth/2factor/sms/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response for SMS/Voice/WhatsApp (202 Accepted)

{
  "result": true
}

Success Response for TOTP (202 Accepted)

{
  "result": true,
  "binding_uri": "otpauth://totp/fast.io:jane@example.com?secret=ABCDEF..."
}

Response Fields (TOTP only)

Error Responses

Notes

• User must have a valid phone number and country code on their account before enabling 2FA (for non-TOTP channels).
• After adding 2FA, it enters unverified state. Must complete verification via POST /current/user/auth/2factor/verify/{token}/.
• For TOTP, display the binding_uri as a QR code for the user to scan.

POST /current/user/auth/2factor/verify/{token}/

Verify a 2FA setup code to confirm enrollment. Transitions 2FA from unverified to enabled state.

Auth: Required (JWT, scope: user or admin)

This is the enrollment step, performed from a fully signed-in session, so the limited twofactor-scope token issued during a 2FA sign-in is refused here with 10175 — that token belongs to POST /current/user/auth/2factor/auth/{token}/, which completes a login rather than confirming enrollment.

Verifying 2FA enrolment is an account-settings operation and requires userdetails:*:rw. A credential that does not explicitly hold that scope is refused with 403 and 10769 (error.params.reason: userdetails_scope_required) — user:*:rw, user:*:rwa, entity-scoped keys and legacy (unscoped) keys alike. A browser login session passes.

Path Parameters

Request Example

curl -X POST "https://api.fast.io/current/user/auth/2factor/verify/123456/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (202 Accepted)

{
  "result": true
}

Verification Failed (406 Not Accepted)

{
  "result": false
}

Error Responses

Notes

• If 2FA is already in the enabled state, returns success without modification.
• This is the final step of the 2FA setup flow.

POST /current/user/auth/2factor/auth/{token}/

Authenticate with a 2FA code. Upgrades a limited-scope JWT to a full-scope JWT.

Auth: Required (JWT, scope: user, twofactor, or admin)

Path Parameters

Request Headers

Request Example

curl -X POST "https://api.fast.io/current/user/auth/2factor/auth/123456/" \
  -H "Authorization: Bearer {twofactor_jwt_token}"

A browser client that opted into the session cookie at sign-in sends the same header again here:

curl -X POST "https://api.fast.io/current/user/auth/2factor/auth/123456/" \
  -H "Authorization: Bearer {twofactor_jwt_token}" \
  -H "x-ve-session-cookie: 1" \
  --cookie-jar cookies.txt

Success Response (200 OK)

{
  "result": true,
  "expires_in": 86400,
  "auth_token": "{jwt_token}"
}

Response Fields

Error Responses

Notes

• This is where a 2FA-enabled account gets its session cookie. Sign-in returns a pre-2FA token and sets no cookie, so a browser client that sent x-ve-session-cookie at sign-in must send the same header again here; otherwise there is no cookie for POST /current/user/auth/bootstrap/ to read.

DELETE /current/user/auth/2factor/{token}/

Disable (remove) 2FA from the account.

Auth: Required (JWT, scope: user or admin)

Path Parameters

Request Example

curl -X DELETE "https://api.fast.io/current/user/auth/2factor/123456/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true
}

Error Responses

Notes

• If 2FA is enabled (verified), a valid 2FA code is required to remove it.
• If 2FA is unverified, it can be removed without a code.
• If 2FA is already disabled, returns success.

2FA Code Delivery Endpoints

Request a 2FA code via different channels. All require auth (accepts user, twofactor, or admin JWT scope).

Success Response (202 Accepted)

{
  "result": true
}

Failure Response (406 Not Accepted)

{
  "result": false
}

Error Responses

Notes

• 2FA must be enabled (or in unverified state) for codes to be sent.
• Returns result: false if the code send fails (e.g., invalid phone number).

Complete 2FA Flows

Complete 2FA Login Flow

1. GET /current/user/auth/
   - Send email:password via HTTP Basic Auth
   - Response includes "2factor": true and limited-scope auth_token

2. GET /current/user/auth/2factor/send/sms/  (or /call/ or /whatsapp/)
   - Request a fresh 2FA code
   - Uses the limited-scope (twofactor) JWT

3. POST /current/user/auth/2factor/auth/{code}/
   - Submit the 2FA code
   - Receive a new JWT with full "user" scope
   - Use this token for all subsequent requests

Complete 2FA Setup Flow

1. POST /current/user/auth/2factor/{channel}/
   - Choose channel: sms, call, whatsapp, or totp
   - Phone number must be configured on account (for non-TOTP)
   - State becomes "unverified"
   - For TOTP: receive binding_uri for QR code

2. Receive code via selected channel (or scan QR code for TOTP)

3. POST /current/user/auth/2factor/verify/{code}/
   - Submit the verification code
   - State becomes "enabled"
   - 2FA is now active on the account

Complete 2FA Removal Flow

1. DELETE /current/user/auth/2factor/{code}/
   - Must provide valid 2FA code if state is "enabled"
   - Can remove without code if state is "unverified"
   - 2FA is fully removed from the account

User Search

GET /current/users/search/

Search for people by name or email across your contacts and the people you share access with (members of orgs, workspaces, and shares you belong to).

Auth: Required (JWT)

Query Parameters

Request Example

curl -X GET "https://api.fast.io/current/users/search/?search=john" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "contacts": {
    "john.doe@example.com": "John Doe",
    "jane.johnson@example.com": "Jane Johnson"
  },
  "users": [
    {
      "id": "1234567890123456789",
      "email": "john.doe@example.com",
      "name": "John Doe"
    },
    {
      "id": null,
      "email": "jane.johnson@example.com",
      "name": "Jane Johnson"
    }
  ]
}

Response Fields

Error Responses

Notes

• Searches across two sources: the people you share access with and your contacts. Results are merged and deduplicated by email.
• contacts is a flat email → name map kept for backward compatibility. users is the richer, id-bearing list — prefer it when you need to act on a specific account.
• A users[].id is only present for matches reachable through a shared space; pure-contact matches carry id: null. When the same email matches both ways, the id-bearing entry wins.

Response Envelope

Success

{"result": true, ...}

Error

{
  "result": false,
  "error": {
    "code": 195654,
    "text": "Human-readable message",
    "documentation_url": "https://api.fast.io/llms.txt",
    "resource": "POST /current/user/"
  }
}

Validation error (HTTP 406) with structured per-parameter detail

{
  "result": false,
  "error": {
    "code": 195654,
    "text": "The email parameter is required. The password must be at least 8 characters.",
    "documentation_url": "https://api.fast.io/llms.txt",
    "resource": "POST /current/user/",
    "params": [
      {"name": "email", "kind": "missing", "message": "The email parameter is required.", "code": 195654},
      {"name": "password", "kind": "invalid", "message": "The password must be at least 8 characters.", "code": 195655, "expected_type": "string"}
    ]
  }
}

error.params is an array of {name, kind, message, code, expected_type?, received_alias?}. It is present on validation errors (HTTP 406) and aggregates every failed parameter so callers see all problems in one round trip. kind is one of missing, invalid, type_mismatch, or unknown_parameter on a validation error, and conflict on a state conflict (HTTP 409). Treat kind as open-ended: handle an unrecognised value as a generic failure rather than rejecting the response. The field is omitted when empty (non-validation errors). The existing text field is retained byte-identically for compatibility and is now advisory — clients should prefer params for programmatic handling.

OPTIONS introspection. Most user/auth endpoints respond to OPTIONS with a JSON description of their accepted parameters (source, required vs optional, expected type, declared constraints). Use this to fetch parameter requirements before issuing a call. Endpoints that don't opt in return 405 Method Not Allowed.

Common Error Codes

Scope and access-mode refusals

Three codes report that a credential was understood but is too narrow for what was asked. All three are HTTP 403, never 401 — the credential is valid, so re-authenticating or refreshing will not help; the credential has to be re-issued with wider scopes from a signed-in web session.

On these four codes error.params is an object (a map), not the per-parameter array returned by validation errors:

On the consent-time 10768 (access_mode_exceeds_initiate) refusals, current_access_mode instead reports the access mode the consent requested, and required_access_mode reports the ceiling the authorization was initiated with.

Branch on error.params.reason, not on the numeric code. Existing entity-permission codes (10545, 10560, 10574, 10753, 10754, 10757, 10175) are unchanged.

Rate Limiting

Response headers: x-ve-limit-avail (requests remaining), x-ve-limit-max (window cap), x-ve-limit-expires (Unix-time the window resets).

When exceeded: HTTP 429 with error code 1671 (Rate Limited). Back off until x-ve-limit-expires.

ID Formats

• User IDs: 19-digit numeric string (e.g., "1234567890123456789")
• "me" can be used as user_id in user endpoints to reference the authenticated user
• User endpoints also accept email address as an identifier

Token Types

Security Best Practices

1. Always use HTTPS for all API communication.
2. Store refresh tokens and API keys securely (OS keychain, encrypted storage).
3. Never log tokens in client-side logs or analytics.
4. Persist the refresh_token from the response; it is long-lived and returned unchanged on refresh (no rotation needed).
5. Verify the state parameter in OAuth callbacks to prevent CSRF.
6. Handle 401 responses by attempting a token refresh; if refresh fails, re-authenticate.
7. Revoke tokens on logout by calling the revoke endpoint and clearing local storage.