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 @MatthiasK,

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 @MatthiasK,
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.

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

In our case the user is connected to the smartlock correctly (we can see this in the Web version), but no invitation e-mail is sent on creation. The deactivation e-mail is received correctly afterwards. Can we debug this somehow?

I have issues creating nuki keys with pin codes. When using the following URL and parameters:

Request URL: https://api.nuki.io/smartlock/17965718244/auth

data:{‘accountUserId’: ‘1555484306’, ‘name’: ‘29646434 #1:SVV-Key-PIN’, ‘remoteAllowed’: False, ‘smartActionsEnabled’: False, ‘allowedFromDate’: ‘2022-10-31T18:0:0.000Z’, ‘allowedUntilDate’: ‘2022-11-02T10:30:0.000Z’, ‘allowedWeekDays’: 0, ‘allowedFromTime’: 0, ‘allowedUntilTime’: 0, ‘code’: 242801, ‘type’: 13}

The key gets created BUT we do not receive your NUKI Email with the invitation to activate the key.
Do you have an idea what the problem is?

Hello Christian,

We found the registered email to be “001nuki@msd-ag.de”. Is this your registered email? Could you please check this account for KP codes?

Sorry for my later answer. This is our registered email address, correct. We have not received any specific email with KP codes (You mean the PIN codes for the nuki keyboard - correct? Can you send us a sample how this email should look like?

Hi Christian,

We send out emails for KP codes and/or invites for the custom integrations but in your case, we do not send out an email if you create just a KP code via the Web API. You would have to send it yourself to the guest. In case you create an authorisation, we send out an invite email, like the below:

Hello!

abc@gmail.com has granted you access to a Nuki Smart Lock.

Open this email on your smartphone and click on the button to accept the invitation:
[Accept invitation]
You can redeem the invitation once within 48h.

If you have any questions, please visit the support center or contact the Nuki support at contact@nuki.io

Best regards,
your Nuki team

Thank you for the answer. So my understanding is, if I create a nuki key with a KP code the nuki key is created including KP code but Nuki does not send out a invitation email in this case. Correct? So the nuki key is unknown to anybody (only to you) but the KP code is active and can be used by the guest to open the door.

Yes, that is correct.

Hi can u please tell me what smart lock Id I put to get smart lock Id’s. I mean to say I want payload input data for smart lock related api’s.

Below error I getting it. ```
“The supplied value ‘123’ for parameter ‘smartlockId’ doesn’t exist”
Can u please help me to add correct SmartlockId