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.

snapauth / sdk

Maintainers

Details