finget / sdk
Official PHP SDK for the Finget passwordless login and notification API
v1.0.1
2026-11-21 12:38 UTC
Requires
- php: ^8.1
- ext-curl: *
- ext-json: *
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Official PHP client for the Finget public API (/api/v1).
Use it on your server to:
- Start passwordless login (“Sign in with Finget”)
- Exchange the one-time callback
codefor a Finget user - Send push notifications to linked users
- Inspect site and notification delivery status
Keep your API key on the server only. Never expose
FINGET_API_KEYin browsers or mobile apps.
Links
| Website | finget.ir |
| Plugins & SDKs | finget.ir/plugins |
| API docs | Provider panel docs |
| Packagist | finget/sdk |
| Laravel package | finget/laravel |
Requirements
- PHP 8.1+
- Extensions:
ext-curl,ext-json
Installation
composer require finget/sdk
Or download the ZIP from finget.ir/plugins and autoload src/ yourself (PSR-4: Finget\\ → src/).
Quick start
export FINGET_API_KEY=fg_live_...
<?php use Finget\Client; use Finget\Exception\ApiException; $finget = Client::fromEnv(); // or: new Client(getenv('FINGET_API_KEY')); $site = $finget->getSite(); // $site['site'] → domain, displayDomain, name, verifiedAt
Authentication (Sign in with Finget)
- In the Finget provider panel, copy your site client ID and register the callback URL.
- Redirect the user to Finget with a CSRF
state. - On callback, verify
state, then exchangecodefor the user profile.
<?php session_start(); use Finget\Client; use Finget\Exception\ApiException; $finget = Client::fromEnv(); $clientId = getenv('FINGET_CLIENT_ID'); // --- Start login --- $login = $finget->loginUrl($clientId); $_SESSION['finget_state'] = $login['state']; header('Location: ' . $login['url']); exit; // --- Callback (must match the URL registered in the panel) --- $expected = $_SESSION['finget_state'] ?? ''; unset($_SESSION['finget_state']); if ( empty($_GET['code']) || !is_string($_GET['state'] ?? null) || !hash_equals($expected, $_GET['state']) ) { header('Location: /login'); exit; } try { $result = $finget->exchangeCode($_GET['code']); } catch (ApiException $e) { header('Location: /login'); exit; } $user = $result['user']; // id, name, phone $isNew = $result['isNew']; // Find or create your local account by $user['id'], then log the user in.
loginUrl()
$login = $finget->loginUrl($clientId); // generates state $login = $finget->loginUrl($clientId, $state); // reuse your own state // ['url' => 'https://finget.ir/auth?client_id=...&state=...', 'state' => '...']
Notifications
Send a notification to one or more linked Finget users (by Finget user id):
$result = $finget->sendNotification([ 'id' => 'order-1234-shipped', // optional idempotency key 'kind' => 'notice', // notice | reminder | security | promo 'title' => 'Your order shipped', 'body' => 'Order 1234 is on the way.', 'link' => [ 'url' => 'https://shop.example/orders/1234', 'label' => 'Track order', ], 'users' => [$user['id']], // or: 'audience' => 'all', ]);
Optional coupon payload:
'coupon' => [ 'code' => 'SAVE10', 'note' => 'Valid this week', 'expiresAt' => '2026-12-31T23:59:59+03:30', ],
Fetch delivery status later:
$status = $finget->getNotification('order-1234-shipped');
API reference
| Method | Description |
|---|---|
Client::fromEnv(?string $apiKeyEnv = 'FINGET_API_KEY') |
Build from environment variables |
getSite(): array |
Validate the API key; return site info |
loginUrl(string $clientId, ?string $state = null): array |
Build the auth redirect URL + state |
createState(int $bytes = 16): string |
Cryptographically secure hex state |
exchangeCode(string $code): array |
Exchange callback code → { user, isNew } |
getUser(string $userId): array |
Refresh a linked user’s profile |
sendNotification(array $payload): array |
Create a notification (HTTP 201) |
getNotification(string $notificationId): array |
Notification status / recipients |
Environment variables
| Variable | Required | Description |
|---|---|---|
FINGET_API_KEY |
yes (for fromEnv) |
Site API key (fg_live_…) |
FINGET_BASE_URL |
no | Override API base (default https://finget.ir/api/v1) |
FINGET_AUTH_URL |
no | Override login page (default https://finget.ir/auth) |
Constructor options
$finget = new Client( apiKey: getenv('FINGET_API_KEY'), baseUrl: 'https://finget.ir/api/v1', authUrl: 'https://finget.ir/auth', timeout: 20, // seconds );
Error handling
use Finget\Exception\ApiException; use Finget\Exception\FingetException; try { $finget->getSite(); } catch (ApiException $e) { // HTTP / network failure from the API $e->getMessage(); $e->status; // 0 if transport failed $e->errorCode; // e.g. invalid_api_key when present $e->body; // decoded JSON body } catch (FingetException $e) { // Client-side validation (empty key, empty code, …) }
Local development
$finget = new Client( apiKey: getenv('FINGET_API_KEY'), baseUrl: 'http://localhost:3001/api/v1', authUrl: 'http://localhost:5173/auth', );
Or set FINGET_BASE_URL / FINGET_AUTH_URL before Client::fromEnv().
Laravel
Prefer the first-party package finget/laravel for routes, config, and the Finget facade. It depends on this SDK.