SearchAF Logo

Authentication#

OAuth and JWT authentication

Initiate OAuth login#

GET/auth/oauth/{provider}/login

Redirects to OAuth provider login page

Parameters#

NameTypeLocationRequiredDescription
providerstring (google, github, shopify)pathYes
redirect_uristringqueryNoPost-login redirect URL

Code Examples#

curl -X GET "https://searchaf.antfly.io/api/v1/auth/oauth/{provider}/login?redirect_uri=value" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "redirect_url": "https://example.com"
}

OAuth callback handler#

GET/auth/oauth/{provider}/callback

Handles OAuth provider callback and generates JWT

Parameters#

NameTypeLocationRequiredDescription
providerstring (google, github, shopify)pathYes
codestringqueryYesOAuth authorization code
statestringqueryYesCSRF protection state

Code Examples#

curl -X GET "https://searchaf.antfly.io/api/v1/auth/oauth/{provider}/callback?code=value&state=value" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "display_name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg",
    "created_at": "2025-10-02T15:30:00Z",
    "updated_at": "2025-10-02T15:30:00Z",
    "last_login_at": "2025-10-02T15:30:00Z",
    "status": "active",
    "settings": {}
  }
}
GET/auth/oauth/{provider}/link

Initiate OAuth flow to link provider to authenticated user account

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Parameters#

NameTypeLocationRequiredDescription
providerstring (google, github, shopify)pathYes
redirect_uristringqueryNoPost-link redirect URL

Code Examples#

curl -X GET "https://searchaf.antfly.io/api/v1/auth/oauth/{provider}/link?redirect_uri=value" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "redirect_url": "https://example.com"
}

Refresh JWT token#

POST/auth/refresh

Generate new JWT from refresh token

Request Body#

Example:

{
    "refresh_token": "string"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/refresh" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "refresh_token": "string"
}'

Responses#

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "display_name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg",
    "created_at": "2025-10-02T15:30:00Z",
    "updated_at": "2025-10-02T15:30:00Z",
    "last_login_at": "2025-10-02T15:30:00Z",
    "status": "active",
    "settings": {}
  }
}

Sign out user#

POST/auth/signout

Clears authentication cookies (access_token and refresh_token)

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/signout" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "success": true
}

Exchange API key for JWT#

POST/auth/apikey/exchange

Exchange a long-lived API key for a short-lived JWT token. The JWT can then be used to authenticate subsequent search and batch requests.

Request Body#

Example:

{
    "api_key": "searchaf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/apikey/exchange" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "api_key": "searchaf_a1b2c3d4_e5f6g7h8i9j0k1l2m3n4o5p6"
}'

Responses#

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 1800
}

Sign up with email and password#

POST/auth/signup

Create a new user account with email and password

Request Body#

Example:

{
    "email": "user@example.com",
    "password": "MySecurePass123!",
    "display_name": "John Doe"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/signup" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "email": "user@example.com",
    "password": "MySecurePass123!",
    "display_name": "John Doe"
}'

Responses#

{
  "success": true,
  "message": "Account created successfully. Please check your email to verify your account.",
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "display_name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg",
    "created_at": "2025-10-02T15:30:00Z",
    "updated_at": "2025-10-02T15:30:00Z",
    "last_login_at": "2025-10-02T15:30:00Z",
    "status": "active",
    "settings": {}
  }
}

Login with email and password#

POST/auth/login

Authenticate with email and password, returns JWT or 2FA challenge

Request Body#

Example:

{
    "email": "user@example.com",
    "password": "MySecurePass123!"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/login" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "email": "user@example.com",
    "password": "MySecurePass123!"
}'

Responses#

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "display_name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg",
    "created_at": "2025-10-02T15:30:00Z",
    "updated_at": "2025-10-02T15:30:00Z",
    "last_login_at": "2025-10-02T15:30:00Z",
    "status": "active",
    "settings": {}
  }
}

Verify email address#

POST/auth/verify-email

Verify email address with token from verification email

Request Body#

Example:

{
    "token": "string"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/verify-email" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "token": "string"
}'

Responses#

{
  "success": true,
  "message": "Email verified successfully. You can now log in."
}

Resend verification email#

POST/auth/resend-verification

Resend verification email to user

Request Body#

Example:

{
    "email": "user@example.com"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/resend-verification" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "email": "user@example.com"
}'

Responses#

{
  "success": true,
  "message": "Verification email sent. Please check your inbox."
}

Request password reset#

POST/auth/forgot-password

Request password reset email

Request Body#

Example:

{
    "email": "user@example.com"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/forgot-password" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "email": "user@example.com"
}'

Responses#

{
  "success": true,
  "message": "If an account exists with this email, a password reset link has been sent."
}

Reset password#

POST/auth/reset-password

Reset password with token from reset email

Request Body#

Example:

{
    "token": "string",
    "new_password": "NewSecurePass123!"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/reset-password" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "token": "string",
    "new_password": "NewSecurePass123!"
}'

Responses#

{
  "success": true,
  "message": "Password reset successfully. You can now log in with your new password."
}

Change password#

POST/auth/change-password

Change password for authenticated user

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "current_password": "string",
    "new_password": "string"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/change-password" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "current_password": "string",
    "new_password": "string"
}'

Responses#

{
  "success": true,
  "message": "Password changed successfully"
}

Setup 2FA#

POST/auth/2fa/setup

Generate TOTP secret and QR code for setting up 2FA

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/2fa/setup" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code_url": "otpauth://totp/SearchAF:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=SearchAF",
  "manual_entry_key": "JBSW Y3DP EHPK 3PXP"
}

Verify and enable 2FA#

POST/auth/2fa/verify-setup

Verify TOTP code and enable 2FA for user account

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "code": "123456",
    "secret": "JBSWY3DPEHPK3PXP"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/2fa/verify-setup" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "code": "123456",
    "secret": "JBSWY3DPEHPK3PXP"
}'

Responses#

{
  "success": true,
  "message": "Two-factor authentication enabled successfully",
  "backup_codes": [
    "ABCD-1234",
    "EFGH-5678"
  ]
}

Disable 2FA#

POST/auth/2fa/disable

Disable 2FA for user account (requires password and TOTP code)

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "password": "string",
    "code": "123456"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/2fa/disable" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "password": "string",
    "code": "123456"
}'

Responses#

{
  "success": true,
  "message": "Two-factor authentication disabled successfully"
}

Verify 2FA code during login#

POST/auth/2fa/verify

Verify TOTP code to complete login with 2FA

Request Body#

Example:

{
    "temp_token": "string",
    "code": "123456"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/2fa/verify" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "temp_token": "string",
    "code": "123456"
}'

Responses#

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "display_name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg",
    "created_at": "2025-10-02T15:30:00Z",
    "updated_at": "2025-10-02T15:30:00Z",
    "last_login_at": "2025-10-02T15:30:00Z",
    "status": "active",
    "settings": {}
  }
}

Regenerate backup codes#

GET/auth/2fa/backup-codes

Generate new set of backup codes (invalidates old ones)

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Code Examples#

curl -X GET "https://searchaf.antfly.io/api/v1/auth/2fa/backup-codes" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "backup_codes": [
    "ABCD-1234",
    "EFGH-5678",
    "IJKL-9012"
  ]
}

Verify backup code during login#

POST/auth/2fa/verify-backup

Verify backup code to complete login when TOTP is unavailable

Request Body#

Example:

{
    "temp_token": "string",
    "backup_code": "ABCD-1234"
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/2fa/verify-backup" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "temp_token": "string",
    "backup_code": "ABCD-1234"
}'

Responses#

{
  "access_token": "string",
  "refresh_token": "string",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "display_name": "John Doe",
    "avatar_url": "https://example.com/avatar.jpg",
    "created_at": "2025-10-02T15:30:00Z",
    "updated_at": "2025-10-02T15:30:00Z",
    "last_login_at": "2025-10-02T15:30:00Z",
    "status": "active",
    "settings": {}
  }
}

Initiate OAuth re-authentication for sensitive operations#

POST/auth/reauth/initiate

Start OAuth re-authentication flow for sensitive operations like ownership transfer

Security#

Provide your bearer token in the Authorization header when making requests to protected resources.

Example: Authorization: Bearer YOUR_API_KEY

Request Body#

Example:

{
    "operation": "transfer_ownership",
    "operation_data": {}
}

Code Examples#

curl -X POST "https://searchaf.antfly.io/api/v1/auth/reauth/initiate" \\
    -H "Authorization: Bearer YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
    "operation": "transfer_ownership",
    "operation_data": {}
}'

Responses#

{
  "provider": "google",
  "auth_url": "https://example.com"
}

OAuth re-authentication callback#

GET/auth/oauth/{provider}/callback/reauth

Handle OAuth callback for re-authentication flow

Parameters#

NameTypeLocationRequiredDescription
providerstring (google, github, shopify)pathYes
codestringqueryYesOAuth authorization code
statestringqueryYesCSRF protection state

Code Examples#

curl -X GET "https://searchaf.antfly.io/api/v1/auth/oauth/{provider}/callback/reauth?code=value&state=value" \\
    -H "Authorization: Bearer YOUR_API_KEY"

Responses#

{
  "success": true
}