snapauth / sdk
SnapAuth SDK
Requires
- php: ^8.1
- composer-runtime-api: ^2.2
- ext-curl: *
Requires (Dev)
- maglnet/composer-require-checker: ^2.0 || ^3.0 || ^4.0
- phpstan/phpstan: ^1.0
- phpstan/phpstan-phpunit: ^1.0
- phpstan/phpstan-strict-rules: ^1.0
- phpunit/phpunit: ^10.0
- squizlabs/php_codesniffer: ^3.5
Conflicts
- nikic/php-parser: <v4.12
This package is auto-updated.
Last update: 2024-10-17 17:35:35 UTC
README
This is the official PHP SDK for SnapAuth.
Documentation
Full API and usage docs are available at the official site.
Installation
composer require snapauth/sdk
Setup
Get your secret key from the dashboard.
Provide it to the SnapAuth\Client
class:
use SnapAuth\Client; $yourSecret = getenv('SNAPAUTH_SECRET_KEY'); $snapAuth = new Client(secretKey: $yourSecret);
Tip
Secret keys are specific to an environment and domain. We HIGHLY RECOMMEND using environment variables or another external storage mechanism. Avoid committing them to version control, as this can more easily lead to compromise.
The SDK will auto-detect the SNAPAUTH_SECRET_KEY
environment variable if you do not provide a value directly.
Usage
Registration
Once you obtain a registration token from your frontend, use the Client
to complete the process and attach it to the user:
$token = 'value_from_frontend'; // $_POST['snapauth_token'] or similar $userInfo = [ 'id' => 'your_user_id', 'username' => 'your_username', ]; $snapAuth->attachRegistration($token, $userInfo);
This activates the passkey and associates it with the user.
$userInfo
will be provided back to you during authentication, so you know who is signing in.
id
should be some sort of stable identifer, like a database primary key.
username
can be anything you want, or omitted entirely.
It's a convenience during client authentication so you don't need to look up the user id again.
This would commonly be the value a user provides to sign in, such as a username or email.
It is not a given name.
Both must be strings, and can be up to 255 characters long. Lookups during authentication are case-insensitive.
Tip
In order to preseve user privacy, we store only a one-way hash of the username
values.
As a result, we cannot return the original value in other API calls.
Authentication
Like registration, you will need to obtain a token from your frontend provided by the client SDK.
Use the verifyAuthToken
method to get information about the authentication process, in the form of an AuthResponse
object.
This object contains the previously-registered User id
.
$token = 'value_from_frontend'; // $_POST['snapauth_token'] or similar $authInfo = $snapAuth->verifyAuthToken($token); // Specific to your application: $authenticatedUserId = $authInfo->user->id; // Laravel: use Illuminate\Support\Facades\Auth; Auth::loginUsingId($authenticatedUserId);
Error Handling
The SnapAuth SDK is written in a fail-secure manner, and will throw an exception if you're not on the successful path. This helps ensure that your integration is easy and reliable.
You may choose to locally wrap API calls in a try/catch
block, or let a general application-wide error handler deal with any exceptions.
All SnapAuth exceptions are an instanceof \SnapAuth\ApiError
.
Compatibility
We follow semantic versioning, and limit backwards-incompatible changes to major versions (the X in X.Y.Z) only.
The SnapAuth SDK is maintained for all versions of PHP with current security support. Since Composer will platform-detect your currently-installed version of PHP, dropping support for older versions is not considered a backwards compatibility break (but you may be unable to install newer versions until updating to a supported version of PHP).
Anything marked as @internal
or any protected
or private
method is not considered in scope for backwards-compatibility guarantees.
Similarly, all methods should be treated as ones that may throw an exception, and as such new types of exceptions are not considered a BC break either.