Web API Example: Create a key for your Nuki Smart Lock

A small example how you could create invite keys for you smart lock via our Web API.
If you got problems or are unsure about how to test it you can use our Swagger Interface to check the commands there first.

You need an ACCESS_TOKEN to do this. See Web API Authentication how to get one first, if this is new for you.

Get the Smart Lock ID

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer ACCESS_TOKEN' 'https://api.nuki.io/smartlock'

Store the smartlockId for you Smart Lock as e.g. SMARTLOCK_ID.

Create a user

To be able to send an e-mail invite for the key we will create we have to create a user first.

To create a user via the web API you need a valid e-mail address EMAIL and an user name USERNAME.

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer ACCESS_TOKEN' -d '{ \
"email": "EMAIL", \
"name": "USERNAME" \
}' 'https://api.nuki.io/account/user'

Get the user ID

curl -X GET --header ‘Accept: application/json’ --header ‘Authorization: Bearer ACCESS_TOKEN’ ‘https://api.nuki.io/account/user

Store the accountUserId for the USERNAME/EMAIL you set as ACCOUNT_USER_ID.

Create a key

A new access authentification for a Smart Lock (‘key’) needs a name KEY_NAME, which is then shown as a Smart Lock permisson in Nuki Web, as well as Boolean values for remoteAllowed (allowing remote lock actions) and smartActionsEnabled (allowing the user to set smart actions like auto-unlock or auto-lock).

Furthermor you can set restrictions to times at which lock actions are allowed for that key.

allowedFromDate (string, optional): General validity start in the format YYYY-MM-DDTHH:MM:SSZ
allowedUntilDate (string, optional): General validity end in the format YYYY-MM-DDTHH:MM:SSZ
allowedWeekDays (integer, optional): The allowed weekdays bitmask: 64 .. monday, 32 .. tuesday, 16 .. wednesday, 8 .. thursday, 4 .. friday, 2 .. saturday, 1 .. sunday
allowedFromTime (integer, optional): Specific allowed from time (in minutes from midnight)
allowedUntilTime (integer, optional): Specific allowed until time (in minutes from midnight); to remove set to ‘Null’

Just leave those values out to not set restrictions.

curl -X PUT --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer ACCESS_TOKEN' -d '{ "accountUserId": ACCOUNT_USER_ID, 
"name": "KEY_NAME", "remoteAllowed": false, 
"smartActionsEnabled": false}' 'https://api.nuki.io/smartlock/SMARTLOCK_ID/auth'

On creation an e-mail with the invite-key is sent to the users EMAIL.

Get the key ID

curl -X GET --header 'Accept: application/json' --header 'Authorization: Bearer ACCESS_TOKEN' 'https://api.nuki.io/smartlock/SMARTLOCK_ID/auth'

Store the id of the auth for the KEY_NAME/ACCOUNT_USER_ID you created as KEY_ID.

Edit a key

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer ACCESS_TOKEN' -d '{ \
"name": "NEW_KEY_NAME" \
}' 'https://api.nuki.io/smartlock/SMARTLOCK_ID/auth/KEY_ID'

Deactivate a key

Just update the key with “enable”: false:

curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Bearer ACCESS_TOKEN' -d '{ \
"enable": false \
}' 'https://api.nuki.io/smartlock/SMARTLOCK_ID/auth/KEY_ID'

Delete a key

curl -X DELETE --header 'Accept: application/json' --header 'Authorization: Bearer ACCESS_TOKEN' 'https://api.nuki.io/smartlock/SMARTLOCK_ID/auth/KEY_ID'

Delete a user

curl -X DELETE --header 'Accept: application/json' --header 'Authorization: Bearer ACCESS_TOKEN' 'https://api.nuki.io/account/user/AccountUserID
This topic will contain a table of contents
1 Like

Hi Stephan,

I’ve tried to follow your guide in a small bash-script but came across some issues in the step to create a new key for an user.
I used ‘https://api.nuki.io/smartlock/$SMARTLOCK_ID/auth’ instead of ‘https://beta.nuki.io/api/smartlock/SMARTLOCK_ID/auth
and I’ve added quotes around ACCOUNT_USER_ID and KEY_NAME.
But I always seem te get the following response: “{“stackTrace”:[],“suppressedExceptions”:[]}”

I’ve also tried to use the url https://beta.nuki.io/api/smartlock/auth and provide the smartlock_id in the json body.
But I received the same error. What might I be doing wrong? How can I debug this?

Kind regards,

Nigel

Thanks for pointing out the errors in my example:

I set this up on our beta-server and forget to change one URL and yes, strings need quotes around them.

User_ID does not need quotes though.

I also will add a link to how to get the correct Authorization bearer if that was unclear or maybe caused the problem.

I couldn’t reproduce your problem. Could you set up a user (as described) or did all requests throw that error?

The best way to debug is to try it out in our Swagger interface first and check the commands you get there:

I did some experiments with the swagger interface and had the same error there.
However when reviewing my earlier commands, I noticed that the I wasn’t using the correct smartlock_id.

So the 403 error with response {“stackTrace”: [], “suppressedExceptions”: []} was just because I didn’t supply the correct smartlock_id.

Thank you for updating your example and helping me out!
(https://api.nuki.io/api/smartlock/SMARTLOCK_ID/auth contains “/api/”, I guess this still needs to be removed)

1 Like

Hello, for my app I need to get the key via web-api for further use via bluetooth api. The question is - how can I get a shared key through web api?

Hello @Stephan,

I try to understand your example a bit more. (I dont have currently http bridge but not sure if I buy it whether my scenario be possible). Considering I generated “key” for the user - how I can share it with him?How the user can use this key to open the lock?

I have Nuki keypad - would it be possible to integrate this generated key with the keypad - so i can just share a pin with the user? And user would use keypad to open the lock?

Regards,
Jan

@jroman In the first step a Nuki Bridge is a device to get remote access to your Smart Lock. If you have a Keypad you can create entry codes for that and just give those to guests.
Additionally you can use the Bridge API (locally) and the Web API (needing a Nuki Web account) to automate tasks. Still authorizations are created on the device itself (locally ore remotely if online and reachable through the Bridge).

Hi @Stephan,
Thank you very much for your answer yet it is still a bit unclear. Please note I am exploring automated way of creating authorisations - doing it from application works fine.

I believe it is only possible with bluetooth API or manually from mobile app.

I was going trough bridge api spec - but I cannot figure out which endpoint could be used for creating authorisation. I would appreciate if you can point me to some reference reading.

So here we arrive at this very topic :slight_smile: Inside authorisation object I can see there is property “code” is it the value that user needs to enter using keypad?

Sorry if my first answer was too general as I was not 100% sure about your usecase.

Yes, this is what you seem to be looking for.
You can set a Keypad entry code (6 digits from 1-9) for an authorization of type=13

See also

1 Like

This post is not displaying anymore there seem to be a JS error in the page

Should be fixed now.