All S4E API requests must be authenticated. The API supports three authentication methods: Bearer token, API key header, and session cookie.

Method 1 --- Bearer Token

Pass your API key in the Authorization header using the Bearer scheme. This is the recommended method for programmatic access.

Authorization: Bearer YOUR_API_KEY

Example

curl -X GET "https://api.s4e.io/api/assets" \
  -H "Authorization: Bearer s4e_live_a1b2c3d4e5f6g7h8i9j0"

Method 2 --- API Key Header

Pass your API key in the X-API-Key custom header.

X-API-Key: YOUR_API_KEY

Example

curl -X GET "https://api.s4e.io/api/assets" \
  -H "X-API-Key: s4e_live_a1b2c3d4e5f6g7h8i9j0"

Method 3 --- Session Cookie

For browser-based access, the API uses session cookies obtained through the login endpoint. This method is primarily used by the S4E web interface.

Obtaining a Session Token

curl -X POST "https://api.s4e.io/api/user/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "your-password",
    "captcha_response": "string",
    "bypass_captcha": false,
    "vendor": "googlev3"
  }'

Response:

{
  "status": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 42,
      "email": "[email protected]",
      "role": "admin"
    }
  }
}

Using the Session Token

Pass the token as a cookie in subsequent requests:

curl -X GET "https://api.s4e.io/api/assets" \
  -b "token=eyJhbGciOiJIUzI1NiIs..."

Or as a query parameter:

curl -X GET "https://api.s4e.io/api/assets?token=eyJhbGciOiJIUzI1NiIs..."

Token Lifecycle

Refreshing a Session

Refresh an active session before it expires:

curl -X POST "https://api.s4e.io/api/user/auth/refresh" \
  -b "token=eyJhbGciOiJIUzI1NiIs..."

This returns a new token with a fresh expiration window.

Logging Out

Invalidate a session token:

curl -X POST "https://api.s4e.io/api/user/auth/logout" \
  -b "token=eyJhbGciOiJIUzI1NiIs..."

Multi-Factor Authentication

If MFA is enabled on the account, the login endpoint returns an intermediate response:

{
  "status": "mfa_required",
  "data": {
    "mfa_token": "mfa_temp_abc123",
    "methods": ["totp", "email"]
  }
}

Complete MFA verification:

curl -X POST "https://api.s4e.io/api/user/auth/mfa/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_token": "mfa_temp_abc123",
    "code": "123456",
    "method": "totp"
  }'

Authentication Errors

Error response format:

{
  "status": "error",
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key."
  }
}

Security Best Practices

• Use API keys with the narrowest scope necessary (see API Keys).
• Rotate API keys regularly --- at least every 90 days.
• Never embed API keys in client-side code or version control.
• Use environment variables or a secrets manager for key storage.
• Enable MFA on all user accounts.
• Monitor the audit log for unauthorized access attempts.

Next Steps

• API Keys for creating and managing API keys.
• Rate Limits for understanding request throttling.