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 valid until their TTL expires.

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. Legacy keys without scopes retain full access.

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.

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-80 chars lowercase alphanumeric + hyphens)
5. Select a paid plan (Starter, Business, or Growth) to activate the org — a new organization must choose a paid plan 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 400. 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). 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=SecureP@ss123" \
  -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
}

Error Responses

Notes

• 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. An SSO-only account (no password) may set an initial password without it; use the password_set field on GET /current/user/details/ to tell which case applies.
• 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.
• 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 Fast.io 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

• The reset code is consumed (deleted) after successful password change.
• A new JWT is created after the password is set.

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",
  "support_hash": "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.

Error Responses

Notes

• Supported providers: google, apple, microsoft.
• 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.

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."
}

The free plan is retired for new organizations, so can_create_free_org is false and a reason is returned. 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).

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/" \
  -H "Authorization: Bearer {jwt_token}"

Success Response (200 OK)

{
  "result": true,
  "shares": [
    {
      "id": "1234567890123456789",
      "name": "Project Files",
      "type": "send",
      "archived": false
    }
  ]
}

Response Fields

Notes

• 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.

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 Example

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

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:SecureP@ss123"

Success Response (200 OK)

{
  "result": true,
  "expires_in": 86400,
  "auth_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "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.
• Account enumeration is intentionally not possible: an unknown email, an SSO-only account (no password), and a wrong password all return the identical 1650/401/"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.

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 (Bearer token — JWT or API key)

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 endpoint does not clear cookies or local storage on the client; the client is responsible for clearing local credential state after sign-out.

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
}

Response Fields

API Keys

POST /current/user/auth/key/

Create a new API key.

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

Request Parameters

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": "abcdefghij1234567890abcdefghij12"
}

Response Fields

Error Responses

Notes

• 2FA verification is required if 2FA is enabled.
• The full key value is only returned at creation time. Subsequent reads return masked versions.

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

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

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

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"
  }
}

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)

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
  }
}

Error Responses

Notes

• Only the fields you send are updated; omitted fields remain unchanged.
• Send empty string or "null" to clear a nullable field.
• 2FA verification is required if 2FA is enabled.

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

Delete an API key.

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

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)

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"
    },
    {
      "id": "key_67890",
      "api_key": "****************************cd34",
      "memo": "Backup Script",
      "created": "2024-02-20 14:00:00 UTC",
      "scopes": null,
      "agent_name": null,
      "expires": null
    }
  ]
}

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)

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)

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 Example

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

Success Response (200 OK)

{
  "result": true,
  "expires_in": 86400,
  "auth_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Fields

Error Responses

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 400) 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 400) and aggregates every failed parameter so callers see all problems in one round trip. kind is one of missing, invalid, or type_mismatch. 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

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.