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.

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 30 days. 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.

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. POST /current/org/{org_id}/create/workspace/ with folder_name, name, perm_join, perm_member_manage

Agent accounts get the agent plan: free, 50 GB storage, 5,000 credits/month, no expiration.

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": "yes",
  "current_api_version": "1.0"
}

Response Fields

Error Responses

Notes

• 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.
• Agent accounts skip email validation requirements and can authenticate immediately.

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": "yes",
  "current_api_version": "1.0"
}

Error Responses

Notes

• Changing the email address resets email verification status.
• 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": "yes",
  "current_api_version": "1.0"
}

Dry Run Response (Cannot Close, 202 Accepted)

{
  "result": "no",
  "current_api_version": "1.0"
}

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/

Check if an email address is already in use.

Auth: None (IP-throttled)

Request Parameters

Request Example

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

Email Available (202 Accepted)

{
  "result": "yes",
  "current_api_version": "1.0"
}

Email In Use (406 Not Acceptable)

{
  "result": "no",
  "current_api_version": "1.0"
}

Error Responses

Notes

• The email is normalized (tags stripped) before lookup.
• result: "yes" = available, result: "no" = already in use.

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": "yes",
  "current_api_version": "1.0"
}

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": "yes",
  "current_api_version": "1.0"
}

Error Responses

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": "yes",
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "email": "jane.doe@example.com"
  },
  "current_api_version": "1.0"
}

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": "yes",
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "supportcode": "1234",
    "support_hash": "a1b2c3d4e5f6..."
  },
  "current_api_version": "1.0"
}

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

GET Response (200 OK)

{
  "result": "yes",
  "response": {
    "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"
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "has_orgs": true,
    "has_workspaces": true,
    "has_shares": false
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "user": {
      "id": "12345678901234567890",
      "account_type": "human",
      "email_address": "jane.doe@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "locked": false,
      "profile_pic": "https://assets.fast.io/..."
    }
  },
  "current_api_version": "1.0"
}

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": "yes",
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "allowed": true
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "can_create_free_org": true,
    "existing_free_orgs": 0,
    "cooldown_remaining": 0,
    "max_free_orgs": 1
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "shares": [
      {
        "id": "12345678901234567890",
        "name": "Project Files",
        "type": "send",
        "archived": false
      }
    ]
  },
  "current_api_version": "1.0"
}

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

Success Response (200 OK)

{
  "result": "yes",
  "response": {
    "invitation": {
      "id": "12345678901234567890",
      "entity": "98765432101234567890",
      "state": "pending",
      "email": "jane.doe@example.com"
    },
    "owner": {
      "id": "11111111111111111111",
      "account_type": "human",
      "email_address": "admin@example.com",
      "first_name": "Admin",
      "last_name": "User",
      "profile_pic": "https://assets.fast.io/..."
    },
    "org": {
      "id": "22222222222222222222",
      "name": "Example Org"
    }
  },
  "current_api_version": "1.0"
}

Response Fields

Error Responses

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/12345678901234567890/public/details/"

Success Response (200 OK)

{
  "result": "yes",
  "response": {
    "invitation": {
      "id": "12345678901234567890",
      "state": "pending"
    },
    "owner": {
      "id": "11111111111111111111",
      "account_type": "human",
      "first_name": "Admin",
      "last_name": "User"
    },
    "org": {
      "id": "22222222222222222222",
      "name": "Example Org"
    }
  },
  "current_api_version": "1.0"
}

Notes

• Returns a more limited view than the authenticated version.
• If the profile or owner cannot be loaded, owner will be null.

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": "yes",
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "invitations": [
      {
        "id": "12345678901234567890",
        "entity": "98765432101234567890",
        "state": "pending",
        "email": "jane.doe@example.com"
      }
    ]
  },
  "current_api_version": "1.0"
}

Response Fields

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"

Success Response (200 OK)

{
  "result": "yes",
  "response": {
    "expires_in": 86400,
    "auth_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "2factor": false
  },
  "current_api_version": "1.0"
}

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.
• SSO-only accounts cannot use this endpoint.

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": "yes",
  "response": {
    "id": "12345678901234567890"
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "auth_type": "jwt_v2",
    "scopes": ["org:12345:rw", "org:67890:rw"],
    "scopes_detail": [],
    "is_agent": true,
    "agent_name": "My MCP Agent",
    "full_access": false
  },
  "current_api_version": "1.0"
}

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-31T23:59:59Z"

Success Response (200 OK)

{
  "result": "yes",
  "response": {
    "api_key": "abcdefghij1234567890abcdefghij12"
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "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"
    }
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "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
    }
  },
  "current_api_version": "1.0"
}

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": "yes",
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "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
      }
    ]
  },
  "current_api_version": "1.0"
}

No Keys Response (200 OK)

{
  "result": "yes",
  "response": {
    "results": 0,
    "api_keys": null
  },
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "state": "enabled",
    "totp": false
  },
  "current_api_version": "1.0"
}

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": "yes",
  "current_api_version": "1.0"
}

Success Response for TOTP (202 Accepted)

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

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": "yes",
  "current_api_version": "1.0"
}

Verification Failed (406 Not Accepted)

{
  "result": "no",
  "current_api_version": "1.0"
}

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": "yes",
  "response": {
    "expires_in": 86400,
    "auth_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  "current_api_version": "1.0"
}

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": "yes",
  "current_api_version": "1.0"
}

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": "yes",
  "current_api_version": "1.0"
}

Failure Response (406 Not Accepted)

{
  "result": "no",
  "current_api_version": "1.0"
}

Error Responses

Notes

• 2FA must be enabled (or in unverified state) for codes to be sent.
• Returns result: "no" 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 users by name or email across contacts and the platform user directory.

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": "yes",
  "response": {
    "contacts": {
      "john.doe@example.com": "John Doe",
      "jane.johnson@example.com": "Jane Johnson"
    }
  },
  "current_api_version": "1.0"
}

Response Fields

Error Responses

Notes

• Searches across two sources: the user's contacts and the platform user directory. Results are merged and deduplicated by email.
• Response format is a flat key-value map (email → name), not an array of objects.

Response Envelope

Success

{"result": "yes", "current_api_version": "1.0", ...}

Error

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

Common Error Codes

Rate Limiting

Response headers: X-Rate-Limit-Available, X-Rate-Limit-Expiry, X-Rate-Limit-Max

When exceeded: HTTP 429 with error code 1671 (1671 (Rate Limited)).

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. Rotate refresh tokens — always store the new token from a refresh response.
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.