Authentication Setup for Nettskjema API

Setting up a client

Before using the functions, you need the following: 1. A registered API client in Nettskjema. 2. Your client credentials (client ID and client secret). These are provided when you register the client.

To register a client go to the nettskjema authorization portal or use the ns_create_client() function to open the url. Here you will be asked to log in with your user account, so you can create the client.

Add Credentials to Your .Renviron File

To prevent hardcoding your credentials in your scripts, add the following entries to your .Renviron file. The .Renviron file is a hidden file in your home directory that R reads on startup.

1. Open your .Renviron file. You can create or edit it with:

file.edit(fs::path_home(".Renviron"))

2. Add your credentials:

NETTSKJEMA_CLIENT_ID=your_client_id
NETTSKJEMA_CLIENT_SECRET=your_client_secret

Replace your_client_id and your_client_secret with the actual values you received from Nettskjema.

3. Save and close the file.

4. Restart your R session to the load changes.

Retrieve the Access Token

Use the ns_auth_token function to retrieve your access token. This function exchanges your client credentials for a valid token. The token is cached by default for efficiency.

library(nettskjemar)

# Try getting your user information
ns_get_me()
#> $isPersonalDataResponsible
#> [1] FALSE
#> 
#> $displayName
#> [1] "ccda25ce-8256-4c6f-ba71-7a4357dc6caf@apiclient"
#> 
#> $logoutLink
#> [1] "/signout"
#> 
#> $isSuperUser
#> [1] FALSE
#> 
#> $isAuthenticated
#> [1] TRUE
#> 
#> $userType
#> [1] "UNKNOWN_ROLE"
#> 
#> $hasAcceptedTos
#> [1] TRUE
#> 
#> $isSupportUser
#> [1] FALSE
#> 
#> $isAdministrativeUser
#> [1] TRUE
#> 
#> $isInLdapGroupUioTils
#> [1] FALSE

If this returns a data.frame of all the forms this client has access to.

By default, the token is stored in your home directory as .nettskjema_token.rds with a 24-hour validity period (max validity of a token). The token is automatically refreshed after the 24–hour period is over, and you as a user should not even notice that this happens.

You can configure the caching path using the cache_path argument of the function, if you are comfortable doing that.

Accessing forms

To access forms, you need to add the client to each form you want it to have access to. This is similar to the procedures necessary in api v2, for those who had experience with that.

Screenshot of the Nettskjema Authorization portal. There is a table with “My clients”, with the header row: Client Id, Username, Client Name, Created and Expires, with three dots at the end for more options. The client id is a SHA hash, and the username is the same SHA has appended with @apiclient.

You will need to go to each Nettskjema forms Settings -> Permissions -> Editing permissions and add the client id in the username format <cliendId>@apiclient to every form you want this specific client to have access to.

This means you can create custom clients with specific user access to particular forms, rather than having a single client with overall access to everything you have access to. While this creates an initial burden of set up, it also allows more control and granularity for security.

Renewing the client secret

The client is valid for one year, at which point you will need to renew it for it to continue working. Renewing means getting a new secret, not a whole new client, meaning the client will retain access to all the forms you have added it to, and you won’t need to re-do that part of the work.

To renew the client, go to the authorization portal, and click the three dots next to the client you want to renew, and choose “Renew”. You will then get a new secret, which you will need to add to you .Renviron file, like before, by replacing the one you already have there.

Adding colleagues

You can give colleagues administrative access to the client by adding them as an “Editor”. Note that adding someone as an editor does not grant them direct access to forms through their user, only to the credentials needed to access specific forms through the API.

By having more editors to a client, means sharing the responsibility of keeping the client up-to-date and renewing it when needed. This is advised so that more people can act quickly if the secret has been leaked by mistake by other team members. Having a couple of editors is a good idea for redundancy, but make sure to limit to only necessary team members.