Skip to content

Commit 45979a1

Browse files
capcom6capcom6
committed
[docs] add JWT sections
1 parent 05c3a89 commit 45979a1

1 file changed

Lines changed: 97 additions & 18 deletions

File tree

‎README.md‎

Lines changed: 97 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
[![PHP Version Require](https://img.shields.io/packagist/php-v/capcom6/android-sms-gateway?style=for-the-badge)](https://packagist.org/packages/capcom6/android-sms-gateway)
66
[![Total Downloads](https://img.shields.io/packagist/dt/capcom6/android-sms-gateway.svg?style=for-the-badge)](https://packagist.org/packages/capcom6/android-sms-gateway)
77

8-
A modern PHP client for seamless integration with the [SMS Gateway for Android](https://sms-gate.app) API. Send SMS messages, manage devices, and configure webhooks through your PHP applications with this intuitive library.
8+
A modern PHP client for seamless integration with the [SMSGate](https://sms-gate.app) API. Send SMS messages, manage devices, and configure webhooks through your PHP applications with this intuitive library.
99

1010
## 🔖 Table of Contents
1111

@@ -17,8 +17,15 @@ A modern PHP client for seamless integration with the [SMS Gateway for Android](
1717
- [🚀 Quickstart](#-quickstart)
1818
- [Sending an SMS](#sending-an-sms)
1919
- [Managing Devices](#managing-devices)
20+
- [🔐 Authentication](#-authentication)
21+
- [Basic Authentication](#basic-authentication)
22+
- [JWT Authentication](#jwt-authentication)
23+
- [Generating a JWT Token](#generating-a-jwt-token)
24+
- [Using a JWT Token](#using-a-jwt-token)
25+
- [Revoking a JWT Token](#revoking-a-jwt-token)
2026
- [📚 Full API Reference](#-full-api-reference)
2127
- [Client Initialization](#client-initialization)
28+
- [Basic Authentication](#basic-authentication-1)
2229
- [Core Methods](#core-methods)
2330
- [Builder Methods](#builder-methods)
2431
- [🔒 Security Notes](#-security-notes)
@@ -36,6 +43,8 @@ A modern PHP client for seamless integration with the [SMS Gateway for Android](
3643
- **Error Handling**: Structured exception management
3744
- **Type Safety**: Strict typing throughout the codebase
3845
- **Encryption Support**: End-to-end message encryption
46+
- **Dual Authentication**: Support for both Basic and JWT authentication
47+
- **Token Management**: Generate, use, and revoke JWT tokens with configurable scopes and TTL
3948

4049
## ⚙️ Prerequisites
4150

@@ -103,36 +112,106 @@ try {
103112
}
104113
```
105114

115+
## 🔐 Authentication
116+
117+
The SMSGate client supports two authentication methods: Basic Authentication and JWT (JSON Web Token) authentication. Each method has its own use cases and benefits.
118+
119+
### Basic Authentication
120+
121+
```php
122+
// Initialize client with Basic authentication
123+
$client = new Client('your_login', 'your_password');
124+
```
125+
126+
### JWT Authentication
127+
128+
JWT authentication uses bearer tokens for authentication.
129+
130+
#### Generating a JWT Token
131+
132+
```php
133+
use AndroidSmsGateway\Client;
134+
use AndroidSmsGateway\Domain\TokenRequest;
135+
136+
// First, create a client with Basic authentication to generate a token
137+
$basicClient = new Client('your_login', 'your_password');
138+
139+
// Create a token request with specific scopes and TTL
140+
$tokenRequest = new TokenRequest(
141+
['messages:send', 'messages:read'], // Scopes for permissions
142+
3600 // Token TTL in seconds (optional)
143+
);
144+
145+
// Generate the token
146+
$tokenResponse = $basicClient->GenerateToken($tokenRequest);
147+
$jwtToken = $tokenResponse->AccessToken();
148+
149+
echo "Token generated! Expires at: " . $tokenResponse->ExpiresAt() . PHP_EOL;
150+
```
151+
152+
#### Using a JWT Token
153+
154+
```php
155+
// Initialize client with JWT authentication
156+
$jwtClient = new Client(null, $jwtToken);
157+
158+
// Now use the client as usual
159+
$message = (new MessageBuilder('Your message text here.', ['+1234567890']))->build();
160+
$messageState = $jwtClient->SendMessage($message);
161+
```
162+
163+
#### Revoking a JWT Token
164+
165+
```php
166+
// Revoke a token using its ID (jti)
167+
$basicClient->RevokeToken($tokenResponse->ID());
168+
echo "Token revoked successfully!" . PHP_EOL;
169+
```
170+
106171
## 📚 Full API Reference
107172

108173
### Client Initialization
174+
175+
The client supports two authentication methods: Basic Authentication and JWT Bearer Tokens.
176+
177+
#### Basic Authentication
109178
```php
110-
$client = new Client(
111-
string $login,
179+
$clientBasic = new Client(
180+
string $login,
112181
string $password,
113182
string $serverUrl = 'https://api.sms-gate.app/3rdparty/v1',
114183
?\Psr\Http\Client\ClientInterface $httpClient = null,
115184
?\AndroidSmsGateway\Encryptor $encryptor = null
116185
);
186+
187+
$clientJWT = new Client(
188+
null, // Set login to null for JWT
189+
string $jwtToken, // JWT token as the second parameter
190+
string $serverUrl = 'https://api.sms-gate.app/3rdparty/v1',
191+
?\Psr\Http\Client\ClientInterface $httpClient = null,
192+
?\AndroidSmsGateway\Encryptor $encryptor = null
193+
);
117194
```
118195

119196
### Core Methods
120197

121-
| Category | Method | Description |
122-
| ------------ | ---------------------------------------------------- | --------------------------------- |
123-
| **Messages** | `SendMessage(Message $message)` | Send SMS message |
124-
| | `GetMessageState(string $id)` | Get message status by ID |
125-
| | `RequestInboxExport(MessagesExportRequest $request)` | Request inbox export via webhooks |
126-
| **Devices** | `ListDevices()` | List registered devices |
127-
| | `RemoveDevice(string $id)` | Remove device by ID |
128-
| **System** | `HealthCheck()` | Check API health status |
129-
| | `GetLogs(?string $from, ?string $to)` | Retrieve system logs |
130-
| **Settings** | `GetSettings()` | Get account settings |
131-
| | `PatchSettings(Settings $settings)` | Partially update account settings |
132-
| | `ReplaceSettings(Settings $settings)` | Replace account settings |
133-
| **Webhooks** | `ListWebhooks()` | List registered webhooks |
134-
| | `RegisterWebhook(Webhook $webhook)` | Register new webhook |
135-
| | `DeleteWebhook(string $id)` | Delete webhook by ID |
198+
| Category | Method | Description |
199+
| ------------------ | ---------------------------------------------------- | --------------------------------- |
200+
| **Messages** | `SendMessage(Message $message)` | Send SMS message |
201+
| | `GetMessageState(string $id)` | Get message status by ID |
202+
| | `RequestInboxExport(MessagesExportRequest $request)` | Request inbox export via webhooks |
203+
| **Devices** | `ListDevices()` | List registered devices |
204+
| | `RemoveDevice(string $id)` | Remove device by ID |
205+
| **System** | `HealthCheck()` | Check API health status |
206+
| | `GetLogs(?string $from, ?string $to)` | Retrieve system logs |
207+
| **Settings** | `GetSettings()` | Get account settings |
208+
| | `PatchSettings(Settings $settings)` | Partially update account settings |
209+
| | `ReplaceSettings(Settings $settings)` | Replace account settings |
210+
| **Webhooks** | `ListWebhooks()` | List registered webhooks |
211+
| | `RegisterWebhook(Webhook $webhook)` | Register new webhook |
212+
| | `DeleteWebhook(string $id)` | Delete webhook by ID |
213+
| **Authentication** | `GenerateToken(TokenRequest $request)` | Generate a new JWT token |
214+
| | `RevokeToken(string $jti)` | Revoke a JWT token by ID |
136215

137216
### Builder Methods
138217
```php

0 commit comments

Comments
 (0)