diff --git a/STYLEGUIDE.md b/STYLEGUIDE.md index cec0356..2bf3567 100644 --- a/STYLEGUIDE.md +++ b/STYLEGUIDE.md @@ -1,65 +1,227 @@ -# Comprehensive Style Guidelines for SMS Gateway Documentation - -## 1. Typography -- **Headings**: Use consistent hierarchy with `#`, `##`, `###` levels -- **Emphasis**: - - Bold (`**text**`) for key terms and mode names - - Italics for occasional emphasis -- **Code**: - - Inline code (`` `code` ``) for API endpoints and parameters - - Code blocks with language specification (```json, ```bash, etc.) -- **Font**: Roboto family (already included in fonts directory) - -## 2. Color Scheme -- Maintain current Material theme palette (light/dark modes) -- Use theme components consistently: - - `!!! note` for additional information - - `!!! tip` for recommendations - - `!!! warning` for cautions - - `!!! failure` for troubleshooting - - `!!! important` for critical notes - -## 3. Visual Elements -- **Emoji**: - - Use in all 1st and 2nd level headers for visual categorization - - Choose emojis relevant to section content (e.g., πŸ”’ for security, βš™οΈ for technical) - - Use Material Design icons (e.g., `:material-message-question:`, `:material-lock-question:`) for additional visual categorization -- **Images**: - - Center-align with `
` or `align=center` - - Specify width for screenshots (e.g., `width="480"`) -- **Diagrams**: - - Use Mermaid for flowcharts and sequence diagrams - - Add descriptive titles to diagrams -- **Grids**: Use Material grid cards (`
`) for feature listings -- **Tabs**: Use tabbed content for multi-language code examples - -## 4. Content Structure -- **Lists**: Use bullet points for features/options, numbered for steps -- **Tables**: For comparison of modes/options -- **Sections**: - - Start with brief overview paragraph - - Break into logical subsections - - End with references/links - -## 5. Code Examples -- **Multi-language Support**: - - Use tabbed content for examples in multiple languages - - Include source links when available -- **Formatting**: - - Use `title` attribute for code blocks to describe purpose - - Add annotations with `// (1)!` and footnotes when needed - - Specify language for syntax highlighting -- **Completeness**: Include complete, runnable examples when relevant - -## 6. Documentation Structure -- **Section Headers**: - - Start with emoji + title - - Follow hierarchy consistently -- **Content Flow**: - - Start with overview paragraph - - Break into logical subsections - - End with "See Also" references -- **Cross-linking**: - - Maintain consistent link formatting with `[]()` - - Use relative paths for internal links (`../file.md`) - - Include relevant links in "See Also" sections +# πŸ“– Comprehensive Style Guidelines for SMS Gateway Documentation + +This document provides a complete reference for maintaining consistency across all documentation files. Follow these guidelines to ensure a professional, cohesive user experience. + +## πŸ“ 1. Typography + +### Headings +- Use consistent hierarchy with `#`, `##`, `###` levels +- **Always place emoji at the beginning** of 1st and 2nd level headings +- Follow the pattern: `# 🎯 Title` not `# Title 🎯` +- Use relevant emojis that match section content + +### Emphasis +- **Bold** (`**text**`) for key terms, mode names, and important concepts +- *Italics* for occasional emphasis or introducing new terms +- Use emphasis sparingly for maximum impact + +### Code +- Inline code (`` `code` ``) for API endpoints, parameters, and technical terms +- Code blocks with language specification (```json, ```bash, ```python, etc.) +- Use `title` attribute for code blocks to describe purpose + +### Font +- Roboto family (already included in fonts directory) +- Let Material theme handle font rendering + +## 🎨 2. Color Scheme + +Maintain current Material theme palette (light/dark modes). Use admonition blocks consistently: + +| Admonition | Usage | +| --------------- | ---------------------------------------------------- | +| `!!! note` | Additional information, supplementary details | +| `!!! tip` | Recommendations, best practices, helpful hints | +| `!!! warning` | Cautions, potential issues, things to watch out for | +| `!!! failure` | Troubleshooting, error explanations, what went wrong | +| `!!! important` | Critical notes, must-know information | +| `!!! success` | Verification steps, successful outcomes | +| `!!! info` | General information, contextual details | +| `!!! danger` | Security warnings, irreversible actions | +| `!!! example` | Code examples, usage demonstrations | + +### Example Usage +```markdown +!!! tip "Best Practices" + - Use short TTLs for tokens + - Store credentials securely + +!!! warning "Important" + This action cannot be undone. Proceed with caution. +``` + +## 🎯 3. Visual Elements + +### Emoji Usage +- **Position**: Always at the **start** of 1st and 2nd level headings +- **Relevance**: Choose emojis that match section content + - πŸ”’ for security/authentication + - βš™οΈ for technical/configuration + - πŸ“± for mobile/device + - πŸš€ for getting started + - πŸ“š for references/see also + - πŸ›‘οΈ for privacy/protection + - ☁️ for cloud services +- **Material Design Icons**: Use for additional visual categorization (e.g., `:material-message-question:`, `:material-lock-question:`) + +### Images +- Center-align with `
` tags or `align=center` attribute +- Specify width for screenshots (e.g., `width="480"`) +- Use descriptive alt text +- Include captions with `
` when appropriate + +### Diagrams +- Use Mermaid for flowcharts and sequence diagrams +- Add descriptive titles to diagrams +- Keep diagrams simple and focused +- Use consistent styling (colors, shapes) + +### Grids +- Use Material grid cards (`
`) for feature listings +- Keep card content concise +- Use consistent card structure + +### Tabs +- Use tabbed content for multi-language code examples +- Use `===` syntax for tab groups +- Keep tab labels short and descriptive + +## πŸ“ 4. Content Structure + +### Lists +- **Bullet points** (`-`) for features, options, and non-sequential items +- **Numbered lists** (`1.`) for steps, procedures, and sequential content +- Keep list items parallel in structure +- Use sub-lists for nested information + +### Tables +- Use for comparison of modes, options, or structured data +- Include descriptive headers +- Keep columns aligned and consistent +- Use tables sparingly for readability + +### Sections +- **Start** with brief overview paragraph +- **Break** into logical subsections with clear headings +- **End** with "See Also" references when appropriate +- Maintain consistent section depth across documents + +## πŸ’» 5. Code Examples + +### Multi-language Support +- Use tabbed content for examples in multiple languages +- Include source links when available +- Prioritize commonly used languages (Python, JavaScript, cURL) + +### Formatting +- Use `title` attribute for code blocks to describe purpose +- Add annotations with `// (1)!` and footnotes when needed +- Specify language for syntax highlighting +- Keep code blocks focused and concise + +### Completeness +- Include complete, runnable examples when relevant +- Show both request and response when helpful +- Include error handling examples for complex operations +- Add comments for non-obvious code sections + +### Example Structure +````markdown +=== "cURL" + ```bash title="Generate JWT Token" + curl -X POST "https://api.sms-gate.app/3rdparty/v1/auth/token" \ + -u "username:password" \ + -H "Content-Type: application/json" \ + -d '{ + "ttl": 3600, + "scopes": ["messages:send"] + }' + ``` + +=== "Python" + ```python title="Generate JWT Token" + import requests + + response = requests.post( + "https://api.sms-gate.app/3rdparty/v1/auth/token", + auth=("username", "password"), + json={"ttl": 3600, "scopes": ["messages:send"]} + ) + ``` +```` + +## πŸ—οΈ 6. Documentation Structure + +### Section Headers +- **Start with emoji + title** (e.g., `## πŸ” Authentication`) +- Follow hierarchy consistently (don't skip levels) +- Keep titles concise and descriptive +- Use parallel structure across similar sections + +### Content Flow +- **Start** with overview paragraph explaining what/why +- **Break** into logical subsections with clear headings +- **End** with "See Also" references linking to related content +- Maintain consistent depth across similar documents + +### Cross-linking +- Maintain consistent link formatting with `[]()` +- Use relative paths for internal links (`../file.md`) +- Use descriptive link text (avoid "click here") +- Include relevant links in "See Also" sections +- Verify all links are functional before publishing + +### File Organization +- Keep related content in the same directory +- Use consistent naming conventions (lowercase, hyphens) +- Include index files for major sections +- Maintain logical navigation structure in `mkdocs.yml` + +## πŸ“‹ 7. Quick Reference + +### Do βœ… +- Place emojis at the **start** of headings +- Use consistent terminology throughout +- Include overview paragraphs for major sections +- Add "See Also" sections with relevant links +- Test code examples before publishing +- Use admonitions appropriately for different content types + +### Don't ❌ +- Place emojis at the **end** of headings +- Skip heading levels (e.g., `##` directly to `####`) +- Use multiple exclamation marks or excessive emphasis +- Include broken or relative links without testing +- Mix different list styles in the same section +- Use code blocks without language specification + +## πŸ“š 8. Examples + +### Good Heading Structure +```markdown +# πŸ” Authentication Guide + +## πŸ“‹ Overview +Brief introduction... + +## πŸ”‘ JWT Tokens +Details about JWT... + +### Token Generation +How to generate tokens... + +## πŸ“š See Also +- [API Reference](../integration/api.md) +``` + +### Admonition Examples +```markdown +!!! tip "Pro Tip" + Use refresh tokens to avoid frequent re-authentication. + +!!! warning "Security Notice" + Never commit tokens to version control. + +!!! note "Important" + JWT authentication is only available in Cloud and Private Server modes. +``` \ No newline at end of file diff --git a/docs/faq/authentication.md b/docs/faq/authentication.md index cabd982..bd0def8 100644 --- a/docs/faq/authentication.md +++ b/docs/faq/authentication.md @@ -1,90 +1,9 @@ -# ❌ FAQ - Authentication - -## 🚫 Why does /auth/token return HTTP 501 in Local Server mode? - -This is expected behavior. JWT authentication is **not implemented in local server mode**. When you make a request to `/auth/token` in local server mode, you will receive HTTP 501 Not Implemented. - -!!! tip "Single API Consistency" - While this breaks the "single API" consistency between local and cloud modes, JWT authentication for local server mode is planned for a future release. +# πŸ” FAQ - Authentication ## πŸ” What is JWT authentication and how does it work? JWT (JSON Web Token) authentication is the primary authentication mechanism for the SMSGate API. It provides a secure, scalable way to authenticate API requests without transmitting credentials with each request. The system supports both access tokens (short-lived) and refresh tokens (long-lived) for seamless token rotation. -## πŸ”„ How do I migrate from Basic Auth to JWT? - -Migrating from Basic Authentication to JWT provides enhanced security, better performance, and fine-grained access control. Here's how to migrate: - -### Step 1: Update Your Code - -Replace Basic Auth with JWT Bearer tokens: - -=== "Before (Basic Auth)" - ```python - response = requests.post( - "https://api.sms-gate.app/3rdparty/v1/messages", - auth=("username", "password"), - json={"phoneNumbers": ["+1234567890"], "textMessage": {"text": "Hello world!"}} - ) - ``` - -=== "After (JWT)" - ```python - # First, get a token - token_response = requests.post( - "https://api.sms-gate.app/3rdparty/v1/auth/token", - auth=("username", "password"), - json={"ttl": 3600, "scopes": ["messages:send"]} - ) - - if token_response.status_code == 201: - token_data = token_response.json() - access_token = token_data["access_token"] - - # Then use the token - response = requests.post( - "https://api.sms-gate.app/3rdparty/v1/messages", - headers={ - "Authorization": f"Bearer {access_token}", - "Content-Type": "application/json" - }, - json={"phoneNumbers": ["+1234567890"], "textMessage": {"text": "Hello world!"}} - ) - ``` - -### Step 2: Implement Token Management - -- **Token Refresh**: Implement automatic token refresh before expiration -- **Error Handling**: Handle 401/403 errors gracefully -- **Secure Storage**: Store tokens securely on the server side - -## πŸ”‘ What are JWT scopes and how do I use them? - -JWT scopes define the permissions associated with a token, implementing the principle of least privilege. All scopes follow the pattern: `resource:action` - -All available scopes are listed in the [Authentication](../integration/authentication.md#jwt-scopes-) section. - -### Using Scopes - -When requesting a JWT token, specify which scopes you need: - -```json -{ - "ttl": 3600, - "scopes": [ - "messages:send", - "messages:read", - "devices:list" - ] -} -``` - -!!! tip "Scope Best Practices" - - Request only the scopes you need - - Create multiple tokens with different scopes for different components - - Use short TTLs for tokens with sensitive scopes - - Avoid using `all:any` unless absolutely necessary - ## ⏰ How long do JWT tokens last and how do I refresh them? JWT tokens have a configurable time-to-live (TTL). The default TTL is 24 hours (86400 seconds), but you can specify a custom duration when generating a token. @@ -182,18 +101,79 @@ class SMSGatewayClient: - Store tokens securely (not in client-side code) - Handle refresh token expiration: Refresh tokens have a longer TTL (default: 720h) but should still be rotated periodically -## πŸ›‘οΈ How do I revoke a JWT token? +## πŸ”‘ What are JWT scopes and how do I use them? -JWT tokens can be revoked before they expire using the token revocation endpoint. This is useful when a token is compromised or no longer needed. +JWT scopes define the permissions associated with a token, implementing the principle of least privilege. All scopes follow the pattern: `resource:action` -### Revoking a Token +All available scopes are listed in the [Authentication](../integration/authentication.md#jwt-scopes-) section. -```bash -curl -X DELETE "https://api.sms-gate.app/3rdparty/v1/auth/token/{jti}" \ - -H "Authorization: Basic username:password" +### Using Scopes + +When requesting a JWT token, specify which scopes you need: + +```json +{ + "ttl": 3600, + "scopes": [ + "messages:send", + "messages:read", + "devices:list" + ] +} ``` -Where `{jti}` is the token ID from the token response. +!!! tip "Scope Best Practices" + - Request only the scopes you need + - Create multiple tokens with different scopes for different components + - Use short TTLs for tokens with sensitive scopes + - Avoid using `all:any` unless absolutely necessary + +## πŸ”„ How do I migrate from Basic Auth to JWT? + +Migrating from Basic Authentication to JWT provides enhanced security, better performance, and fine-grained access control. Here's how to migrate: + +### Step 1: Update Your Code + +Replace Basic Auth with JWT Bearer tokens: + +=== "Before (Basic Auth)" + ```python + response = requests.post( + "https://api.sms-gate.app/3rdparty/v1/messages", + auth=("username", "password"), + json={"phoneNumbers": ["+1234567890"], "textMessage": {"text": "Hello world!"}} + ) + ``` + +=== "After (JWT)" + ```python + # First, get a token + token_response = requests.post( + "https://api.sms-gate.app/3rdparty/v1/auth/token", + auth=("username", "password"), + json={"ttl": 3600, "scopes": ["messages:send"]} + ) + + if token_response.status_code == 201: + token_data = token_response.json() + access_token = token_data["access_token"] + + # Then use the token + response = requests.post( + "https://api.sms-gate.app/3rdparty/v1/messages", + headers={ + "Authorization": f"Bearer {access_token}", + "Content-Type": "application/json" + }, + json={"phoneNumbers": ["+1234567890"], "textMessage": {"text": "Hello world!"}} + ) + ``` + +### Step 2: Implement Token Management + +- **Token Refresh**: Implement automatic token refresh before expiration +- **Error Handling**: Handle 401/403 errors gracefully +- **Secure Storage**: Store tokens securely on the server side ## πŸ” "Invalid token" JWT Error @@ -268,36 +248,6 @@ The "token expired" error occurs when the JWT token has passed its expiration ti - Handle token expiration gracefully in your code - Consider clock skew in your expiration logic -## 🚫 "Token revoked" JWT Error - -The "token revoked" error occurs when a JWT token has been manually revoked before its natural expiration time. - -### Common Causes - -1. **Manual Revocation**: Token was explicitly revoked by an administrator -2. **Security Incident**: Token was revoked due to a security concern - -### Troubleshooting Steps - -1. **Request New Token**: Generate a new token with the same scopes, or use the refresh token if available - ```bash - curl -X POST "https://api.sms-gate.app/3rdparty/v1/auth/token" \ - -u "username:password" \ - -H "Content-Type: application/json" \ - -d '{ - "ttl": 3600, - "scopes": ["messages:send", "messages:read"] - }' - ``` - - Or use the refresh token endpoint: - ```bash - curl -X POST "https://api.sms-gate.app/3rdparty/v1/auth/token/refresh" \ - -H "Authorization: Bearer " - ``` - -2. **Investigate Revocation Reason**: Contact support to understand why the token was revoked - ## πŸ™… "Scope required" JWT Error The "scope required" error occurs when the JWT token doesn't have the necessary scope to access a specific resource or perform a specific action. @@ -347,94 +297,52 @@ The "scope required" error occurs when the JWT token doesn't have the necessary - Create multiple tokens for different purposes - Regularly review and update your scope requirements -## πŸ”„ "Migration from Basic Auth to JWT" Issues +## 🚫 "Token revoked" JWT Error -When migrating from Basic Authentication to JWT, you may encounter various issues. Here are common problems and their solutions. +The "token revoked" error occurs when a JWT token has been manually revoked before its natural expiration time. -### Common Issues +### Common Causes -1. **Token Generation Errors**: Unable to generate JWT tokens -2. **Permission Errors**: JWT tokens don't have the same permissions as Basic Auth -3. **Code Compatibility**: Existing code doesn't work with JWT authentication -4. **Refresh Token Implementation**: Need to implement refresh token logic for long-running applications +1. **Manual Revocation**: Token was explicitly revoked by an administrator +2. **Security Incident**: Token was revoked due to a security concern ### Troubleshooting Steps -1. **Verify Token Generation**: Ensure you can generate JWT tokens successfully - ```bash - curl -X POST "https://api.sms-gate.app/3rdparty/v1/auth/token" \ - -u "username:password" \ - -H "Content-Type: application/json" \ - -d '{"ttl": 3600, "scopes": ["messages:send"]}' - ``` - -2. **Update Code Gradually**: Migrate code incrementally rather than all at once - ```python - # Hybrid approach during migration - def make_request(endpoint, data=None, use_jwt=True): - if use_jwt and jwt_token: - headers = {"Authorization": f"Bearer {jwt_token}"} - else: - # Fall back to Basic Auth - headers = {} - auth = (username, password) - - return requests.post(endpoint, headers=headers, auth=auth, json=data) - ``` - -3. **Implement Refresh Token Logic**: Use refresh tokens to obtain new access tokens without re-authenticating - ```python - # Refresh token when access token expires - if datetime.now() + timedelta(minutes=5) >= token_expires_at: - new_token = refresh_access_token() - ``` - -4. **Test in Staging**: Test JWT authentication in a staging environment before production - -!!! tip "Migration Best Practices" - - Keep Basic Auth as a fallback during transition - - Monitor authentication errors during migration - - Implement refresh token logic for long-running applications +1. **Request New Token**: Generate a new token with the same scopes, or use the refresh token if available + ```bash + curl -X POST "https://api.sms-gate.app/3rdparty/v1/auth/token" \ + -u "username:password" \ + -H "Content-Type: application/json" \ + -d '{ + "ttl": 3600, + "scopes": ["messages:send", "messages:read"] + }' + ``` + + Or use the refresh token endpoint: + ```bash + curl -X POST "https://api.sms-gate.app/3rdparty/v1/auth/token/refresh" \ + -H "Authorization: Bearer " + ``` -## πŸ›‘οΈ JWT Security Issues +2. **Investigate Revocation Reason**: Contact support to understand why the token was revoked -JWT tokens are generally secure, but improper implementation can lead to security vulnerabilities. +## πŸ›‘οΈ How do I revoke a JWT token? -### Common Security Issues +JWT tokens can be revoked before they expire using the token revocation endpoint. This is useful when a token is compromised or no longer needed. -1. **Long TTLs**: Using excessively long token expiration times -2. **Token Leakage**: Tokens being exposed in logs, browser storage, or network traffic -3. **Insufficient Scopes**: Using overly broad scopes like `all:any` -4. **Refresh Token Security**: Refresh tokens have longer TTLs and should be stored securely +### Revoking a Token -### Troubleshooting Steps +```bash +curl -X DELETE "https://api.sms-gate.app/3rdparty/v1/auth/token/{jti}" \ + -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" +``` -1. **Review Token TTL**: Ensure your token TTL is appropriate for your use case - ```json - { - "ttl": 3600, // 1 hour - reasonable for most use cases - "scopes": ["messages:send"] - } - ``` +Where `{jti}` is the token ID from the token response. -2. **Implement Secure Storage**: Ensure tokens are stored securely - ```python - # Example of secure token storage - from cryptography.fernet import Fernet - - key = Fernet.generate_key() - cipher_suite = Fernet(key) - encrypted_token = cipher_suite.encrypt(jwt_token.encode()) - ``` -3. **Secure Refresh Tokens**: Store refresh tokens securely and rotate them periodically - ```python - # Store refresh token securely - encrypted_refresh_token = cipher_suite.encrypt(refresh_token.encode()) - ``` +## πŸ”— See Also -!!! tip "Security Best Practices" - - Use the shortest practical TTL for your use case - - Store tokens securely on the server side - - Implement proper token revocation - - Store refresh tokens securely and rotate them periodically +- [Authentication Guide](../integration/authentication.md) - Complete authentication documentation +- [Cloud Server Setup](../getting-started/public-cloud-server.md) - Initial setup guide +- [Private Server Setup](../getting-started/private-server.md) - Self-hosted deployment diff --git a/docs/faq/errors.md b/docs/faq/errors.md index dfc3a52..6c671d7 100644 --- a/docs/faq/errors.md +++ b/docs/faq/errors.md @@ -24,8 +24,8 @@ The app requires the `android.permission.SEND_SMS` permission to send SMS messag 2. Navigate to Permissions β†’ SMS and enable it !!! note "Community Contribution" - Special thanks to *@mabushey* and *@AlexxIT* for the SMS permission solution! - [:material-github: Issue #184](https://github.com/capcom6/android-sms-gateway/issues/184) + Special thanks to *@mabushey* and *@AlexxIT* for the SMS permission solution! + [:material-github: Issue #184](https://github.com/capcom6/android-sms-gateway/issues/184) [:material-github: Issue #280](https://github.com/capcom6/android-sms-gateway/issues/280) === "Via ADB" @@ -76,25 +76,12 @@ This error indicates the system has blocked further messages to prevent abuse. K - [How can I avoid mobile operator restrictions?](./general.md#how-can-i-avoid-mobile-operator-restrictions) FAQ entry. -## πŸ“Ά `RESULT_RIL_MODEM_ERR` Error - -The `RESULT_RIL_MODEM_ERR` error usually indicates a problem with the device's modem or the communication between the application and the modem. This error can stem from various causes: - -- SIM card not properly seated -- Outdated modem firmware - -!!! tip "Troubleshooting Checklist" - 1. :material-restart: Reboot device - 2. :material-sim: Clean SIM contacts with alcohol swab - 3. :material-update: Install latest OS updates - 4. :material-factory: Reset network settings - ## πŸ“± `RESULT_NO_DEFAULT_SMS_APP` Error The `RESULT_NO_DEFAULT_SMS_APP` error occurs when no default SMS app is set on the device or when the default SIM for sending SMS messages hasn't been configured. To resolve this issue, follow these steps: -1. Open :gear: Settings β†’ Apps β†’ Default apps -2. Select default messaging app +1. Open :gear: Settings β†’ Apps β†’ Default apps +2. Select default messaging app 3. Choose preferred SIM for sending in the default messaging app !!! tip "API Workaround" @@ -108,24 +95,37 @@ The `RESULT_NO_DEFAULT_SMS_APP` error occurs when no default SMS app is set on t } ``` +## πŸ“Ά `RESULT_RIL_MODEM_ERR` Error + +The `RESULT_RIL_MODEM_ERR` error usually indicates a problem with the device's modem or the communication between the application and the modem. This error can stem from various causes: + +- SIM card not properly seated +- Outdated modem firmware + +!!! tip "Troubleshooting Checklist" + 1. :material-restart: Reboot device + 2. :material-sim: Clean SIM contacts with alcohol swab + 3. :material-update: Install latest OS updates + 4. :material-factory: Reset network settings + ## πŸ“΄ `Can't send message: No SIMs found` Error This error occurs when the app cannot detect any SIM cards on the device. There are several possible causes for this issue: -=== "Hardware Issues" +=== "Hardware Issues" - - :material-sim-alert: SIM not fully inserted - - :material-chip: SIM card has poor contact + - :material-sim-alert: SIM not fully inserted + - :material-chip: SIM card has poor contact - :material-wrench: Damaged SIM tray -=== "Software Issues" +=== "Software Issues" 1. :material-shield-refresh: For Xiaomi devices: - Enable Developer Options (tap Build Number 7x) - Disable MIUI optimizations to prevent the app from requesting permissions repeatedly - Reboot device - 2. :material-key-chain: Ensure the app has all required permissions in your device settings or via ADB. + 2. :material-key-chain: Ensure the app has all required permissions in your device settings or via ADB. ```bash adb shell pm list permissions | grep READ_PHONE_STATE ``` diff --git a/docs/faq/general.md b/docs/faq/general.md index fa9ebab..c8f0fde 100644 --- a/docs/faq/general.md +++ b/docs/faq/general.md @@ -11,29 +11,6 @@ Making SMSGate the default SMS app could solve this problem, but we intentionall - Set a strong PIN code - Use a dedicated Android device -## πŸ“Έ Can I send MMS messages? - -The SMSGate app focuses on core SMS functionality and does not support sending MMS (Multimedia Messaging Service) messages. This design choice aligns with the principle of "do one thing, do it well"β€”ensuring reliable SMS delivery without complicating the application with additional, less critical features. - -## πŸ€– Does the app support Android 15 and higher? - -The SMSGate app fully supports Android 15 (API level 35) and higher. However, there are two important considerations when installing and configuring the app on these newer Android versions. - -=== "Installation" - - On Android 15+, Google Play Protect may block APK installation because the app is not distributed via Google Play. - Follow the [installation guide](../installation.md#installing-from-apk) for the step-by-step APK flow, including the Play Protect fallback. - - !!! warning "Security Note" - Only disable Play Protect temporarily for the installation. Re-enable it immediately after the app is installed, and download APKs only from the official GitHub releases page. - -=== "Permissions" - - Due to enhanced privacy and security changes in Android 15+, the SMS permission may be grayed out in the Settings app by default. You must grant it [manually](./errors.md#does-not-have-androidpermissionsend_sms-error). - -!!! note "Related Issue" - See [Issue #280](https://github.com/capcom6/android-sms-gateway/issues/280) for community reports and discussion. - ## πŸ“± How can I send an SMS using the second SIM card? The SMSGate app supports sending messages from multiple SIM cards simultaneously. To utilize a secondary SIM card for message sending, please refer to the comprehensive [Multi-SIM Support](../features/multi-sim.md) section for detailed setup instructions and configuration options. @@ -44,27 +21,27 @@ The SMSGate app is designed to work reliably even when power saving modes are en ### Local Mode 🏠 -- **Power saving settings:** +- **Power saving settings** The app provides an option to disable battery optimizations directly from the *Settings* tab under the "System" section. This helps ensure uninterrupted operation. The app also uses a foreground service with a wake lock, which allows it to function reliably even with power-saving mode enabled. -- **Battery impact:** +- **Battery impact** Using a wake lock and disabling battery optimizations may lead to increased battery consumption. ### Cloud Mode ☁️ -- **Power saving settings:** +- **Power saving settings** Similar to Local Mode, disabling battery optimizations can enhance reliability. However, the app primarily relies on Firebase Cloud Messaging (FCM) push notifications, which functions without requiring power-saving mode to be turned off. -- **Potential delays:** +- **Potential delays** High message rates could cause occasional delays when the device is in power-saving mode due to FCM's limitations on high-priority notifications. !!! tip "Recommendation" - - **Testing:** + - **Testing** Test the app with and without battery optimizations disabled to evaluate its performance on your device and Android version. - - **Device manufacturers:** + - **Device manufacturers** Behavior may vary depending on the device manufacturer and specific Android customizations. - - **Local + Cloud:** + - **Local + Cloud** For maximum responsiveness, consider using a local server alongside the cloud connection. - - **Don't Kill My App:** + - **Don't Kill My App** Follow the [Don't Kill My App](https://dontkillmyapp.com) guide to ensure the app is not killed by the operating system. ## πŸ“¨ How do I enable or disable delivery reports for messages? @@ -127,20 +104,21 @@ graph TD C --> G["system:ping webhook"] ``` -### Local mode +=== "Local mode" -Attempting to connect to the device's API directly can give you an immediate sense of its online status. Accessing the `/health` endpoint is a straightforward way to do this. + Attempting to connect to the device's API directly can give you an immediate sense of its online status. Accessing the `/health` endpoint is a straightforward way to do this. -### Cloud mode +=== "Cloud/Private mode" -The app operates asynchronously, relying on PUSH notifications rather than maintaining a continuous connection to the server. You can use the `GET /device` endpoint to obtain some information about the device's state. The response includes a `lastSeen` field, showing the last time the device connected to the server. Due to the app's idle mode behavior, the device may only connect to the server once every 15 minutes, meaning the `lastSeen` time may not always represent the current status. + The app operates asynchronously, relying on PUSH notifications rather than maintaining a continuous connection to the server unless SSE is used. + You can use the `GET /device` endpoint to obtain some information about the device's state. The response includes a `lastSeen` field, showing the last time the device connected to the server. Due to the app's idle mode behavior, the device may only connect to the server once every 15 minutes, meaning the `lastSeen` time may not always represent the current status. -### Any mode +=== "Any mode" -Irrespective of the mode, you can register a `system:ping` webhook to monitor the device's online status. This webhook will notify your server about the status of the app at user-defined intervals, set within the app's Settings on the device. This feature offers a proactive approach to track connectivity and ensure the device is functioning as expected across any operational mode. + Irrespective of the mode, you can register a `system:ping` webhook to monitor the device's online status. This webhook will notify your server about the status of the app at user-defined intervals, set within the app's Settings on the device. This feature offers a proactive approach to track connectivity and ensure the device is functioning as expected across any operational mode. -!!! warning "Caution" - Using the ping feature will increase battery usage. It's important to balance the need for frequent status updates with the impact on device battery life, especially if the device is expected to operate for extended periods without charging. + !!! warning "Caution" + Using the ping feature will increase battery usage. It's important to balance the need for frequent status updates with the impact on device battery life, especially if the device is expected to operate for extended periods without charging. ## πŸ“› Can I send SMS with a custom sender name? @@ -150,14 +128,54 @@ The app uses your SIM card to send messages, so by default, it uses the same sen Contact your mobile provider for: - Alphanumeric Sender ID services - - Business SMS solutions + - Business SMS solutions ## πŸ”‘ How do I change my password? -| Mode | Documentation | -| ------------- | ------------------------------------------------------------------------------------ | -| Local | [Server Config](../getting-started/local-server.md#server-configuration) | -| Cloud/Private | [Password Management](../getting-started/public-cloud-server.md#password-management) | +=== "Local Mode" + 1. Open the app and navigate to **Settings** + 2. Go to **Local Server** + 3. Tap **Credentials** β†’ **Password** + 4. Enter your new password (at least 8 characters) + 5. Stop and restart the server using the button at the bottom to apply changes + + !!! warning "Server Restart Required" + After changing credentials, you must stop and restart the local server for the changes to take effect. + +=== "Cloud/Private Mode" + 1. Open the app and navigate to **Settings** + 2. Go to **Cloud Server** + 3. Tap **Credentials** β†’ **Password** + 4. Enter your new password (at least 14 characters) + 5. Confirm the changes + + !!! danger "Important" + - Password changes take effect immediately across all devices + - You will need to re-authenticate with the new password on all clients + - For Private Server mode, the same password management process applies + +## πŸ“Έ Can I send MMS messages? + +The SMSGate app focuses on core SMS functionality and does not support sending MMS (Multimedia Messaging Service) messages. This design choice aligns with the principle of "do one thing, do it well"β€”ensuring reliable SMS delivery without complicating the application with additional, less critical features. + +## πŸ€– Does the app support Android 15 and higher? + +The SMSGate app fully supports Android 15 (API level 35) and higher. However, there are two important considerations when installing and configuring the app on these newer Android versions. + +=== "Installation" + + On Android 15+, Google Play Protect may block APK installation because the app is not distributed via Google Play. + Follow the [installation guide](../installation.md#installing-from-apk) for the step-by-step APK flow, including the Play Protect fallback. + + !!! warning "Security Note" + Only disable Play Protect temporarily for the installation. Re-enable it immediately after the app is installed, and download APKs only from the official GitHub releases page. + +=== "Permissions" + + Due to enhanced privacy and security changes in Android 15+, the SMS permission may be grayed out in the Settings app by default. You must grant it [manually](./errors.md#does-not-have-androidpermissionsend_sms-error). + +!!! note "Related Issue" + See [Issue #280](https://github.com/capcom6/android-sms-gateway/issues/280) for community reports and discussion. ## πŸ’¬ Does the app support RCS messaging? diff --git a/docs/faq/local-server.md b/docs/faq/local-server.md index a6656d4..056c353 100644 --- a/docs/faq/local-server.md +++ b/docs/faq/local-server.md @@ -1,30 +1,17 @@ # ❓ FAQ - Local Server -## 🌐 Why can't I access the local server from the internet? - -The public IP address displayed in the Local Server section is only accessible from the internet if: - -1. Your ISP assigns a public ("white") IP address to your device -2. Your router/firewall allows incoming connections to the specified port and has a port-forwarding rule to the device’s local IP - -!!! warning "CG-NAT Issue" - Many ISPs use Carrier-Grade NAT (CG-NAT), which assigns shared addresses and blocks direct internet connections to devices. This is the default for many providers. - -### Solutions ⚑ - -If your public IP address is not accessible from the internet due to CG-NAT or other network restrictions, consider these workarounds: +## πŸ“΅ Why does the Local Server disconnect on my Android device? -1. **Obtain Public IP from ISP** πŸ”§ - Contact your internet service provider and request a public IP address assignment. +The Android OS may kill background apps to save battery, causing the Local Server to stop running. This is common on certain devices, especially those from Xiaomi, Samsung, and other manufacturers known for aggressive battery optimization. -2. **Use Tunneling Services** πŸ”€ - Set up secure tunneling with tools like [ngrok](https://ngrok.com/) or [Cloudflare Tunnel](https://www.cloudflare.com/products/tunnel/). These run on your device or a computer and expose a public endpoint. +To prevent this: -3. **Use Dynamic DNS** 🧭 - If you have a public (but dynamic) IP, configure Dynamic DNS (DDNS) on your router to keep a stable hostname pointed at your device. +- Keep your device connected to a charger while using the app +- Disable battery optimization directly from the app: in SMS Gate, open **Settings β†’ System** and tap the battery optimization option +- Alternatively, disable battery optimization for SMS Gate in your Android device settings +- Follow specific instructions for your phone model at [dontkillmyapp.com](https://dontkillmyapp.com/) -4. **Switch to Cloud Server Mode** ☁️ - Use [Cloud Server mode](../getting-started/public-cloud-server.md), which works with any internet connection without requiring public IP configuration. +Additionally, check if the SMS Gate notification icon is still visible in the status bar (a persistent notification is shown while the Local Server is running). If it's missing, the app was likely killed by the OS. ## πŸ“Ά How can I check the online status of the device in Local mode? @@ -33,26 +20,28 @@ You can verify the device's online status with two quick checks: 1. **API health** – open `http://:/health` in a browser or HTTP client. A successful response confirms the Local Server is running. 2. **Network reachability** – run `ping ` from your PC. If there is no response, the Wi-Fi connection may have dropped, often due to the phone's Wi-Fi entering a low-power mode. -## πŸ“΅ Why does the Local Server disconnect on my Android device? +## 🌐 Why can't I access the local server from the internet? -The Android OS may kill background apps to save battery, causing the Local Server to stop running. This is common on certain devices, especially those from Xiaomi, Samsung, and other manufacturers known for aggressive battery optimization. +The public IP address displayed in the Local Server section is only accessible from the internet if: -To prevent this: +1. Your ISP assigns a public ("white") IP address to your device +2. Your router/firewall allows incoming connections to the specified port and has a port-forwarding rule to the device's local IP -- Keep your device connected to a charger while using the app -- Disable battery optimization directly from the app: in SMS Gate, open **Settings β†’ System** and tap the battery optimization option -- Alternatively, disable battery optimization for SMS Gate in your Android device settings -- Follow specific instructions for your phone model at [dontkillmyapp.com](https://dontkillmyapp.com/) +!!! warning "CG-NAT Issue" + Many ISPs use Carrier-Grade NAT (CG-NAT), which assigns shared addresses and blocks direct internet connections to devices. This is the default for many providers. -Additionally, check if the SMS Gate notification icon is still visible in the status bar (a persistent notification is shown while the Local Server is running). If it's missing, the app was likely killed by the OS. +### Solutions ⚑ -## πŸ”‘ How do I change my password in Local mode? +If your public IP address is not accessible from the internet due to CG-NAT or other network restrictions, consider these workarounds: -For Local mode, password management is handled through the [Server Configuration](../getting-started/local-server.md#server-configuration) section. +1. **πŸ”§ Obtain Public IP from ISP** + Contact your internet service provider and request a public IP address assignment. -## πŸ” What authentication methods are supported in Local Server mode? +2. **πŸ”€ Use Tunneling Services** + Set up secure tunneling with tools like [ngrok](https://ngrok.com/) or [Cloudflare Tunnel](https://www.cloudflare.com/products/tunnel/). These run on your device or a computer and expose a public endpoint. -Local Server mode **only supports Basic Authentication**. JWT authentication is not available in this mode. +3. **🧭 Use Dynamic DNS** + If you have a public (but dynamic) IP, configure Dynamic DNS (DDNS) on your router to keep a stable hostname pointed at your device. -!!! tip "Future Support" - JWT authentication for local server mode is planned for a future release to provide a consistent API across all deployment modes. +4. **☁️ Switch to Cloud Server Mode** + Use [Cloud Server mode](../getting-started/public-cloud-server.md), which works with any internet connection without requiring public IP configuration. diff --git a/docs/faq/private-server.md b/docs/faq/private-server.md new file mode 100644 index 0000000..8493669 --- /dev/null +++ b/docs/faq/private-server.md @@ -0,0 +1,65 @@ +# ❓ FAQ - Private Server + +## πŸ“± Why can't the Android app connect to my private server? + +If the Android app cannot find or connect to your private server, check the following: + +### 1. API URL Format + +The API URL **must** include the full path `/api/mobile/v1`. Using just the base URL will not work. + +!!! example "Correct URL Format" + ```text + https://private.example.com/api/mobile/v1 + ``` + +!!! danger "Common Mistake" + The cloud server uses URL rewriting where `api.sms-gate.app` already contains the `api` part. With a private server, you must include `/api` in the path. + +### 2. HTTPS Requirement + +The Android app **requires HTTPS** for all communications with your private server unless you use an insecure build variant. Using HTTP will result in connection failures. + +!!! tip "SSL Certificate Options" + - Use [Let's Encrypt](https://letsencrypt.org/) for a free, trusted certificate + - Use our [project CA](../services/ca.md) for private IP addresses + - Use a tunneling service like [ngrok](https://ngrok.com/) or [Cloudflare Tunnel](https://www.cloudflare.com/products/tunnel/) for testing + +### 3. Network Connectivity + +Ensure your server is accessible from the device's network: + +- Check firewall rules allow incoming connections on your server port +- Verify DNS resolution if using a domain name +- Test connectivity with `curl https://your-server.com/health` from the device network + +## πŸ“Š How do I verify my private server is working? + +Test your server with a health check: + +```bash +curl https://private.example.com/health +``` + +A successful response returns JSON with server status information. + +!!! tip "SSL Verification" + If using a self-signed certificate, you may need to use `curl -k` or `curl --insecure` for testing, but the Android app requires a valid certificate. + +## πŸ“« How do I send messages from external applications? + +To send messages or interact with your private server from external applications, you must use the **`/api/3rdparty/v1`** endpoint. + +!!! example "Sending Messages via API" + ```bash + curl -X POST "https://private.example.com/api/3rdparty/v1/messages" \ + -u "username:password" \ + -H "Content-Type: application/json" \ + -d '{ + "phoneNumbers": ["+1234567890"], + "textMessage": {"text": "Hello World"} + }' + ``` + +!!! note "URL Path Difference" + The cloud server uses `https://api.sms-gate.app/3rdparty/v1/messages` because the domain already contains `api`. With a private server, you need `/api/3rdparty/v1/...`. diff --git a/docs/features/private-server.md b/docs/features/private-server.md index 0ae31ad..5007699 100644 --- a/docs/features/private-server.md +++ b/docs/features/private-server.md @@ -1,4 +1,4 @@ -# Private Server πŸ›‘οΈ +# πŸ›‘οΈ Private Server To enhance privacy and control, you can host your own private server. This keeps all message data within your infrastructure while maintaining push notification capabilities through our public server at `api.sms-gate.app`. This setup eliminates the need to configure Firebase Cloud Messaging (FCM) or rebuild the Android app, but it does demand some technical know-how. @@ -43,7 +43,7 @@ flowchart ```
-## Prerequisites βœ… +## βœ… Prerequisites === "🐳 With Docker" - Docker installed on Linux VPS @@ -58,7 +58,7 @@ flowchart === "πŸ“¦ With Helm" - Kubernetes cluster with Helm 3+ -## Installation Methods πŸ“¦ +## πŸ“¦ Installation Methods === "🐳 With Docker" @@ -130,7 +130,7 @@ flowchart For detailed Helm chart documentation, see [Helm Chart Documentation](https://github.com/android-sms-gateway/server/blob/master/deployments/helm-chart/README.md). -## Reverse Proxy Configuration 🌐 +## 🌐 Reverse Proxy Configuration ### Example Nginx Configuration @@ -142,6 +142,14 @@ location / { } ``` +!!! note "API URL Structure" + When configuring clients to interact with your private server, remember that the URL path must include `/api` as a prefix: + + - **Android App**: `https://your-domain.com/api/mobile/v1` + - **External API Calls**: `https://your-domain.com/api/3rdparty/v1/...` + + This differs from the cloud server (`api.sms-gate.app`) where the `api` part is in the domain name. See [Getting Started with Private Server](../getting-started/private-server.md#using-the-api) for details. + ### Advanced Configuration For SSL termination and advanced routing scenarios, consider: @@ -152,7 +160,7 @@ For SSL termination and advanced routing scenarios, consider: - Setting up rate limiting - Implementing proxying for SSE connections -## Background Worker βš™οΈ +## βš™οΈ Background Worker The background worker operates as a separate process from the main server and handles these core maintenance tasks: diff --git a/docs/getting-started/local-server.md b/docs/getting-started/local-server.md index 53cc6fe..346cfd4 100644 --- a/docs/getting-started/local-server.md +++ b/docs/getting-started/local-server.md @@ -42,23 +42,6 @@ To access the **Swagger UI** for API documentation and testing, follow these ste - **Security** – same authentication as the API - **Convenience** – no manual `curl` commands - -### βš™οΈ Server Configuration - -To modify the port, username, or password: - -1. Open the app and navigate to the "Settings" tab -2. Locate the "Local Server" section -3. Update the port, username, or password as needed -4. Return to the "Home" tab -5. Stop and restart the server using the button at the bottom of the screen to apply the changes - -#### Requirements - -* Port number must be between 1024 and 65535 -* Username must be at least 3 characters long -* Password must be at least 8 characters long - ## πŸ“š See Also - [Public Cloud Server Mode](./public-cloud-server.md) for internet-accessible messaging diff --git a/docs/getting-started/private-server.md b/docs/getting-started/private-server.md index 1599fd0..23f359c 100644 --- a/docs/getting-started/private-server.md +++ b/docs/getting-started/private-server.md @@ -1,6 +1,6 @@ -# Getting Started πŸš€ +# πŸš€ Getting Started -## Private Server πŸ”’ +## πŸ”’ Private Server To enhance privacy and control, you can host your own private server. This keeps all message data within your infrastructure while maintaining push notification capabilities through our public server at `api.sms-gate.app`. This setup eliminates the need to configure Firebase Cloud Messaging (FCM) or rebuild the Android app, but it does demand some technical know-how. @@ -152,6 +152,15 @@ To run the server, you'll need: !!! note "API URL Path" The API URL **must** include the `/api/mobile/v1` path. Using just the base URL (e.g., `https://private.example.com`) will not work. + !!! warning "HTTPS Required" + The Android app **requires HTTPS** for all communications with your private server unless you use an insecure build variant. Using HTTP will result in connection failures. + + To obtain a valid SSL certificate: + + - Use [Let's Encrypt](https://letsencrypt.org/) for a free, trusted certificate + - Use our [project CA](../services/ca.md) for private IP addresses or internal domains + - Use a tunneling service like [ngrok](https://ngrok.com/) or [Cloudflare Tunnel](https://www.cloudflare.com/products/tunnel/) for testing + 3. **Activate connection** 1. Switch to **Home** tab 2. Activate **Cloud server** switch @@ -168,14 +177,41 @@ To run the server, you'll need: !!! info "Automatic Registration" No manual registration step is required. Username and password are generated automatically on the first successful connection to the server. -### Password Management πŸ”‘ +### Using the API πŸ“‘ + +All API interactions with the SMSGate use the same request format and authentication methods, but the URL structure differs between Cloud and Private server modes. + +#### URL Structure Comparison + +| Component | Cloud Server | Private Server | +| ------------ | ----------------------------------------------- | -------------------------------------------------- | +| Base URL | `https://api.sms-gate.app` | `https://your-domain.com` | +| API Path | `/3rdparty/v1/...` | `/api/3rdparty/v1/...` | +| Full Example | `https://api.sms-gate.app/3rdparty/v1/messages` | `https://your-domain.com/api/3rdparty/v1/messages` | -Identical to [Cloud Server mode](public-cloud-server.md#password-management). +!!! note "Why the Difference?" + The cloud server uses URL rewriting where the domain `api.sms-gate.app` already contains the `api` part. With a private server, you need to explicitly include `/api` in the URL path. + +#### Example: Sending a Message + +```bash +# Cloud Server +curl -X POST "https://api.sms-gate.app/3rdparty/v1/messages" \ + -u "username:password" \ + -H "Content-Type: application/json" \ + -d '{"phoneNumbers": ["+1234567890"], "textMessage": {"text": "Hello"}}' + +# Private Server +curl -X POST "https://your-domain.com/api/3rdparty/v1/messages" \ + -u "username:password" \ + -H "Content-Type: application/json" \ + -d '{"phoneNumbers": ["+1234567890"], "textMessage": {"text": "Hello"}}' +``` --- -## See Also πŸ“š +## πŸ“š See Also - [Private Server Documentation](../features/private-server.md) - [Ubuntu/Docker/Nginx Setup Guide](https://github.com/capcom6/android-sms-gateway/discussions/50) diff --git a/docs/getting-started/public-cloud-server.md b/docs/getting-started/public-cloud-server.md index 5a1ad8d..68b9b6f 100644 --- a/docs/getting-started/public-cloud-server.md +++ b/docs/getting-started/public-cloud-server.md @@ -1,6 +1,6 @@ -# Getting Started πŸš€ +# πŸš€ Getting Started -## Cloud Server ☁️ +## ☁️ Cloud Server Use Cloud Server mode when your device has dynamic or shared IP addresses. Start immediatelyβ€”no registration, email, or phone number required. @@ -175,20 +175,6 @@ Change the notification channel in the app settings: }); ``` -#### Password Management πŸ” - -!!! danger "Security Requirements" - - :material-form-textbox-password: Minimum 14 characters - - :material-text: No reuse of previous passwords is recommended - - :material-clock-alert: Changes take immediate effect - -**Update Steps**: - -1. :gear: Settings β†’ Cloud Server -2. :material-key: Credentials β†’ Password -3. :material-form-textbox-password: Enter new password -4. :material-check: Confirm changes - --- [:material-book-open: Full API Documentation](https://api.sms-gate.app/) diff --git a/docs/index.md b/docs/index.md index 86a95cb..c622961 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,7 +22,7 @@ SMS Gateway for Android turns your Android smartphone into an SMS and MMS gatewa - πŸ“œ **Multipart messages:** Send long messages with auto-partitioning. - πŸ“Š **Message status tracking:** Monitor the status of sent messages in real-time. - πŸ”” **Real-time incoming message notifications:** Receive instant SMS and MMS notifications via [webhooks](./features/webhooks.md). -- πŸ“– **Retrieve previously received messages:** Access your message history via [Reading Messages](./features/reading-messages/). +- πŸ“– **Retrieve previously received messages:** Access your message history via [Reading Messages](./features/reading-messages.md). πŸ”’ Security and Privacy: diff --git a/docs/integration/authentication.md b/docs/integration/authentication.md index 092d1e2..549cccf 100644 --- a/docs/integration/authentication.md +++ b/docs/integration/authentication.md @@ -1,4 +1,4 @@ -# Integration - Authentication πŸ”’ +# πŸ”’ Integration - Authentication This guide provides a comprehensive overview of authentication in the SMSGate API. JWT authentication is the primary mechanism for securing API access, providing a robust and scalable way to authenticate requests. @@ -9,9 +9,6 @@ The SMSGate supports multiple authentication methods to accommodate different us - **Basic Authentication**: Legacy username/password for backward compatibility - **JWT Bearer Tokens**: Primary authentication mechanism with configurable TTL and refresh token support -!!! important "JWT Authentication Availability" - JWT authentication is only available in **Public Cloud Server** mode. In **Local Server** mode, only Basic Authentication is supported. - JWT authentication is recommended for all new integrations as it provides better security, scalability, and fine-grained access control through scopes. ## JWT Authentication πŸ” @@ -665,7 +662,7 @@ print("Message sent:", result) - **Token Storage**: Store tokens securely (e.g., HttpOnly cookies, secure server-side storage) - **CSRF Protection**: Implement CSRF protection for web applications -## See Also πŸ”— +## πŸ”— See Also - [API Reference](api.md) - Complete API endpoint documentation - [Integration Guide](index.md) - Overview of integration options diff --git a/mkdocs.yml b/mkdocs.yml index 985589e..ad18923 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -32,7 +32,6 @@ theme: name: Switch to system preference nav: - Home: index.md - - Blog: blog/index.md - Installation: installation.md - Getting Started: - Overview: getting-started/index.md @@ -47,30 +46,23 @@ nav: - Authentication: integration/authentication.md - Libraries: integration/client-libraries.md - CLI: integration/cli.md + - Webhooks: features/webhooks.md - GET to POST: integration/get-to-post.md - Agent Systems: integration/agents.md - - Webhooks: features/webhooks.md - Features: - - Private Server: features/private-server.md - Sending Messages: features/sending-messages.md + - Reading Messages: features/reading-messages.md - Webhooks: features/webhooks.md - - Multi-SIM Support: features/multi-sim.md + - Status Tracking: features/status-tracking.md - Multi-Device Support: features/multi-device.md + - Multi-SIM Support: features/multi-sim.md - MMS Support: features/mms.md - - Status Tracking: features/status-tracking.md + - Data SMS Support: features/data-sms.md - Health Checks: features/health.md - Ping: features/ping.md - - Reading Messages: features/reading-messages.md - - Data SMS Support: features/data-sms.md + - Private Server: features/private-server.md - Logging: features/logging.md - Settings Management: features/settings-management.md - - Services: - - Certificate Authority: services/ca.md - - Twilio Fallback: services/twilio-fallback.md - - Pricing: pricing.md - - Privacy: - - Policy: privacy/policy.md - - Encryption: privacy/encryption.md - FAQ: - General: faq/general.md - Local Server: faq/local-server.md @@ -78,17 +70,25 @@ nav: - Reading Messages: faq/reading-messages.md - Errors: faq/errors.md - Authentication: faq/authentication.md + - Private Server: faq/private-server.md - Resources: - Examples: resources/examples.md - - Third-Party: resources/3rdparty.md - Use Cases: resources/use-cases.md + - Third-Party: resources/3rdparty.md + - Services: + - Twilio Fallback: services/twilio-fallback.md + - Certificate Authority: services/ca.md + - Blog: blog/index.md + - Pricing: pricing.md + - Privacy: + - Policy: privacy/policy.md + - Encryption: privacy/encryption.md - Contributing: contributing.md - License: license.md validation: omitted_files: warn absolute_links: warn unrecognized_links: warn - anchors: warn plugins: - search - render_swagger @@ -99,7 +99,8 @@ plugins: htmlmin_opts: remove_comments: true cache_safe: true - - social + - social: + enabled: !ENV [CI, false] - git-revision-date-localized: enable_creation_date: true - blog: @@ -137,4 +138,4 @@ markdown_extensions: - pymdownx.blocks.caption - pymdownx.details - pymdownx.inlinehilite - - pymdownx.snippets + - pymdownx.snippets \ No newline at end of file