Frequently asked questions

What is darvis/nuki?

A Laravel package for the NUKI Web API. It lists, locks and unlocks NUKI smartlocks, reads the activity log, manages keypad codes, receives NUKI webhooks and ships Livewire pages for all of it. It is open source under the MIT license and free to use; you need your own NUKI account.

How do I lock or unlock a NUKI smart lock from a Laravel application?

Install darvis/nuki, put a personal API token in NUKI_API_TOKEN, and call the facade. Nuki::smartlocks()->all() lists the locks as SmartLock objects, and Nuki::smartlocks()->unlock($id) and lock($id) send the command. The call goes to the NUKI Web API, not to the lock itself, and returns nothing; no exception means NUKI accepted it.

Which PHP, Laravel and Livewire versions does darvis/nuki need?

PHP 8.2 or higher, Laravel 11, 12 or 13, Livewire 3.5 or higher (or Livewire 4) and Flux 2, of which the free edition is enough. Livewire and Flux are Composer requirements, so they are installed with the package, also when you only use the facade.

Where do I get the NUKI API token the package asks for?

In the NUKI Web account that owns the locks, on web.nuki.io, under API. The token gives access to every lock on that account, so treat it as a password and keep it in .env. For more than one account, store a token per account in the nuki_accounts table, where it is encrypted.

Can one Laravel application manage the locks of several NUKI accounts?

Yes. With NUKI_TOKEN_RESOLVER=database, the default, every row in nuki_accounts is an account with its own encrypted token, and Nuki::as('tenant-42') scopes a call to one of them. OAuth 2.0 is the other way, where the owner of each account gives access instead of handing over a token; for that you build the callback route yourself.

Is it safe to install a package that can open my doors?

The bundled pages are closed by default. Outside the local environment they answer 403 until your application defines the viewNuki gate, and self registration is off. The webhook receiver rejects every request without a valid HMAC signature, and API and OAuth tokens in the database are encrypted. Routes you build yourself with the facade are yours to protect.

How do I receive NUKI webhooks in Laravel?

Set NUKI_WEBHOOK_ENABLED=true and NUKI_WEBHOOK_SECRET, register the callback URL with php artisan nuki:webhook-register, and listen for the NukiWebhookReceived event. The receiver checks the HMAC-SHA256 signature of the body, ignores a repeat of the same event id for ten minutes and then dispatches the event. Without a secret it rejects every request.

Can I give someone access to one specific lock without touching the NUKI account?

Yes. With NUKI_AUTH_USERS_ENABLED=true the package has its own darvis-nuki guard with login, an emailed login code and password reset. A main user adds sub users and gives each of them lock, unlock, log and authorization rights per smartlock, with a period and weekdays. Those permissions live in your database only; nothing is written back to NUKI.

Can I try darvis/nuki without owning a NUKI lock?

Yes. With NUKI_DEMO=true every call to the NUKI Web API is answered with made up locks, logs and keypad codes, and a seeder adds four demo accounts. It is meant for screenshots and demos, never for production.

How do I test code that uses darvis/nuki without calling NUKI?

Fake the HTTP layer with Http::fake(['api.nuki.io/*' => ...]) and set nuki.token_resolver to config with a test token. Darvis\Nuki\Support\DemoFixtures has payloads in the shape of the real answers. Set nuki.http.retries to 1, or a faked 5xx is sent three times.