Guest Access Codes API

nile exposes a guest portal access code public api for customers who want to automate the lifecycle of guest access codes with this api, you can discover guest portals that use access code authentication create and manage generic access codes (shared codes not tied to a specific guest) create and manage guest‑specific access codes (per‑guest codes with name and email tied to the access code) update start or end time for the access codes as required delete access codes when they are no longer needed prerequisites create a guest portal for access code authentication enable a guest portal and configure its authentication type as access code in the nile cloud services portal decide whether the portal will use generic access codes or guest specific access codes; a single portal cannot use both models simultaneously generate api key from the nile portal, go to the security tab and create an api key when you save, an api key json file will be generated this will look like { "api token" "08d552ef4c423f8d ", "name" "accesscode tests", "url" "https //u1 nile global cloud", "validbeforetime" "2026 11 10t20 30 00z" } the api token is used as a bearer token in the authorization header the url is the api base url for all requests documented below this key is scoped to allow only apis in the access codes workflow discovering guest portals with authentication as access‑code before creating access codes, you will need to find the portal id for the guest portal that uses access code authentication using the api get \<base url from nile>/api/v1/portalconfig/summary this will list the guest portals and identify which ones are configured with access code authentication example request get /api/v1/portalconfig/summary http/1 1 host \<base url from nile> authorization bearer \<api token> example response { "content" \[ { "id" "3d81e0a4 b4e3 485c b7dd 8c6e1128e441", "name" "guestpopserviceportal", "portaltype" "access code", "tenantid" "e40319a4 0fd5 4e85 81c9 890d949ae6c1", "genericaccesscode" false, "geoscope" { "sites" \[ { "id" "5f8b4aae acc8 4cd1 bcf0 fc7f8683f273", "name" "5f8b4aae acc8 4cd1 bcf0 fc7f8683f273" } ], "buildings" \[], "floors" \[], "zones" \[] } } ], "totalelements" 1 } key fields portaltype must be "access code" for use with access codes genericaccesscode true → portal uses generic access codes false → portal uses guest‑specific access codes the guest portal id is provided in the first line of the example above as "id" this value will be used as {portalid} in all subsequent api requests creating generic access codes if your portal is configured with genericaccesscode = true, the same api post \<base url from nile>/api/v2/portalconfig/{portal id}/access codes can be used to create generic access codes that are not tied to a specific guest these codes are ideal when you want a single access code printed in a lobby or front desk you do not need per‑guest attribution on the backend option 1 generic access code a single shared access code that can be used by multiple guests characteristics the administrator has the option to define a custom access code, or nile can automatically generate one one access code shared across all guests not tied to an individual guest time bound (start and end time) simple to distribute verbally, via signage, or email typical use cases short duration events meetings or training sessions temporary guest access where individual tracking is not required { "expires" true, "generateperguest" false, "starttime" "2026 01 16t00 00 00z", "endtime" "2026 01 18t00 00 00z", "sendemail" false, "usetags" false, "targets" \[ { "accesscode" "123455555" }] } result the response contains one entry per generic access code, each with its own start and end time because these are generic codes, no guest name or guest email fields are present, and any guest who knows a valid code can use it to gain access through that portal creating guest‑specific access codes option 2 user specific access code a unique access code per guest , tied to user identity characteristics one access code per guest the administrator has the option to define a custom access code, or nile can automatically generate one associated with the guest's name and email address time bound (start and end time) enables traceability and personalized distribution typical use cases employee hosted visitors contractors or partners conferences and events requiring individual access control integration with helpdesk or registration systems once the portal is configured with genericaccesscode = false, you can create access codes that are tied to individual guests using the api post \<base url from nile>/api/v2/portalconfig/{portal id}/access codes all variants of the api share the same basic request structure expires – whether the codes expire starttime, endtime – validity window (utc, iso 8601) generateperguest – generate codes per guest (true) or expect them in the payload (false) sendemail – whether to send emails to guests (if configured for your tenant) usetags – whether geo/tags are used targets – one object per guest example request 1 pre defined access code per guest in this scenario, you must explicitly specify which access codes are assigned to each user based on their name and email for example, for a conference, you can use the guest registration id as the access code and map with guest username and email { "expires" true, "starttime" "2026 02 12t00 02 00z", "endtime" "2026 02 13t23 58 00z", "generateperguest" false, "sendemail" false, "usetags" false, "targets" \[ { "accesscode" "12345678", "guestname" "john doe" , "guestemail" "johndoe\@mycompany com" }, { "accesscode" "abcd123", "guestname" "jane doe ", "guestemail" "janedoe\@gmail com" }, { "accesscode" "12345678", "guestname" "thomas edison", "guestemail" "tedision\@electric com" } ] } } settings { encodeurl true timeout 0 } result here, the admin defines access code explicitly for each guest, and all guests share the same validity window example request 2 system‑generated access code per guest if you are able to share codes with guests in advance, you can rely on nile to generate access codes for each user you only need to pass the user’s name and email as attributes via the api for example, the help desk can generate these codes and send them to guests via email { "expires" true, "starttime" "2025 11 14t00 02 00z", "endtime" "2025 11 15t23 58 00z", "generateperguest" true, "sendemail" false, "usetags" false, "targets" \[ { "guestname" "jane austen", "guestemail" "austen\@gmail com" } ] } result nile returns a unique access code and all metadata for each guest, along with a success message such as "message" "successfully created 1 access code(s)" example request 3 shared event code for multiple guests in this scenario, a single access code is shared by multiple guests from the same organization for example, at a conference center where several vendors/exhibitors are present, you can assign one access code per company and use it for all guests belonging to that company { "expires" true, "starttime" "2025 12 01t00 00 00z", "endtime" "2025 12 31t23 59 59z", "sharedacesscode" "event2026", "generateperguest" false, "sendemail" false, "usetags" false, "targets" \[ { "guestname" "la croix", "guestemail" "foo\@lacroix com" }, { "guestname" "foo bar", "guestemail" "emma bar\@lacroix com" } ] } result the response contains one entry per guest, all with the same access code and a summary field sharedaccesscode "event2026" update guest‑specific access codes you can also update parameters such as start time, end time and access code for guest‑specific using the following api put \<base url from nile>/api/v2/portalconfig/{portal id}/access codes you will have to provide the guest email and name as attributes in the request body as they remain contsant and cannot be updated you must include the guest’s email and name as attributes in the request body because these values are fixed at creation time and cannot be modified later example request updation of access codes { "expires" true, "generateperguest" false, "starttime" "2026 02 02t00 02 00z", "endtime" "2027 02 13t23 58 00z", "sendemail" false, "usetags" false, "targets" \[ { "guestemail" "janedoe2\@gmail com", "guestname" "jane doe" }] } result if a matching entry exists for the specified email, the parameters get updated for the same get system generated access codes use the api to obtain a system generated access code by sending a get request to \<base url from nile>/api/v2/portalconfig/{portal id}/access codes deleting guest‑specific access codes once the event is completed, you can clean up guest‑specific access codes by deleting them using the following api delete \<base url from nile>/api/v2/portalconfig/{portal id}/access codes you will have to provide the guest email and name as parameters in the request body example request deletion of guest access code { "targets" \[ { "guestemail" "ben5\@gmail com", "guestname" "ben schmitt5" } ] } result if a matching entry exists for the specified email, the api returns http 204 no content to indicate that the delete operation succeeded