darvis/nuki

Laravel package for the NUKI Web API (smartlocks, logs, authorizations, webhooks).

v1.0.2 2026-05-12 17:38 UTC

Requires

• php: ^8.2
• ext-json: *
• laravel/framework: ^11.0|^12.0|^13.0
• livewire/flux: ^2.0
• livewire/livewire: ^3.5|^4.0

Requires (Dev)

• laravel/pint: ^1.27
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.0|^4.0
• pestphp/pest-plugin-laravel: ^3.0|^4.0

MIT

• Arvid de Jong

• api
• laravel
• webhook
• iot
• nuki
• smartlock

README

A Laravel package for the NUKI Web API. Provides a clean, typed interface for managing smartlocks, fetching activity logs, managing authorizations (keypad codes / app users), and receiving webhook callbacks.

• PHP 8.2+ — Laravel 11, 12, 13
• Bearer (API token) and OAuth 2.0 Authorization Code support
• Account-aware: a single application can manage multiple NUKI accounts
• Webhook receiver with HMAC signature verification and idempotent dispatch
• Built-in Livewire 3.5+ / 4 + Flux 2 UI: dashboard, activity timeline, smartlocks, keypad authorizations, webhooks and OAuth status
• Optional self-contained user-auth (darvis-nuki guard) with email OTP, sub-users, per-smartlock permissions and a weekday bitmask

Documentation

Full developer documentation lives in docs/. Quick links:

• Getting started — install, publish, "hello world".
• Configuration reference — every NUKI_* env var and config/nuki.php key.
• NUKI API authentication — token mode, OAuth, multi-account scoping with Nuki::as().
• API reference — every public method on every resource, plus DTOs and console commands.
• Users and permissions — package-managed users, sub-user permissions, weekday bitmask, OTP, password reset.
• Auth routes — every URL registered when the auth feature is on.
• Webhooks — signature verification, dedup, NukiWebhookReceived event.
• UI and localization — Livewire components, locales, layout override.
• Demo mode — NUKI_DEMO=true, seeded accounts.
• Troubleshooting — common errors and fixes.

Installation

composer require darvis/nuki
php artisan vendor:publish --tag=nuki-config
php artisan migrate

Service provider and Nuki facade are auto-discovered.

Minimal .env (token mode, single account)

NUKI_AUTH=token
NUKI_TOKEN_RESOLVER=config
NUKI_API_TOKEN=your-personal-api-token-from-web-nuki-io

Generate the token in the NUKI Web portal under API. For multi-account or OAuth, see NUKI API authentication.

Hello world

use Darvis\Nuki\Facades\Nuki;

$locks = Nuki::smartlocks()->all();          // Collection<SmartLock>
$lock  = Nuki::smartlocks()->find($id);      // SmartLock

Nuki::smartlocks()->lock($id);
Nuki::smartlocks()->unlock($id);

$entries = Nuki::logs()->forSmartlock($id, ['limit' => 50]);

Nuki::auths()->create($id, [
    'name' => 'Cleaning lady',
    'type' => 13,                            // keypad code
    'code' => 123456,
]);

For everything else — every method on every resource, the DTO shapes, multi-account, OAuth, webhooks, the bundled UI, the optional user-auth — see docs/.

Webhooks

NUKI_WEBHOOK_ENABLED=true
NUKI_WEBHOOK_SECRET=a-long-random-string

Listen for inbound events:

use Darvis\Nuki\Events\NukiWebhookReceived;

Event::listen(NukiWebhookReceived::class, function (NukiWebhookReceived $event) {
    // $event->type, $event->payload, $event->accountKey
});

See docs/webhooks.md for signature verification, deduplication and registering the callback with NUKI.

Demo mode

NUKI_DEMO=true

Intercepts every call to api.nuki.io and answers with realistic canned data. Combine with php artisan db:seed --class="Darvis\\Nuki\\Database\\Seeders\\NukiDemoSeeder" to populate the multi-account switcher. Perfect for screenshots and walk-throughs; never enable in production. See docs/demo-mode.md.

User authentication (optional)

NUKI_AUTH_USERS_ENABLED=true
php artisan nuki:user-create --email=[e-mail] --name=Admin --password=secret123

Registers a darvis-nuki auth guard, gates /nuki/* behind it, and ships login / OTP / register / password-reset Livewire screens. Main users can create sub-users with per-smartlock permissions, a validity window and a weekday bitmask. See docs/users-and-permissions.md.

Testing

composer test

Credits

• Author: Arvid de Jong (Darvis) — [e-mail] — https://darvis.nl

License

MIT — see LICENSE.