Authentication

The Platform API lets advanced users build external applications or dashboards that interact with the Platform. However, you still need to authenticate in order to access any information via the Platform API.

If you are logged in to the RiskScape Platform in your web browser, you are already authenticated. You can browse /api URLs directly and you can view the data that your user account has access to.

This is the easiest way to explore the API, but it relies on your browser’s login session, so it is not suitable for a script. For scripting, we recommend using access tokens.

Access tokens

An access token gives you access to the Platform without without needing your password. Access tokens are like a password though, in that they are credentials that potentially grant access to anything that you have access to in the Platform.

Warning

Store your access tokens securely. Do not hard-code them into scripts where other people may see them. Using environment variables to pass tokens through to scripts is a good approach to avoid storing credentials in plain-text script files.

You can generate an access token from your profile page. Go to your profile page and look for “Access tokens”. You can create two kinds of access tokens:

• A personal access token, for authenticating your own API requests, e.g. from scripts or other tools. API access tokens last for 180 days (6 months).

• A WebDAV token, for accessing the RiskScape Platform file storage over WebDAV.

Tip

When you create a token, specifying a description can help you tell your tokens apart later, e.g. “laptop script” or “dashboard integration”.

The token is shown to you once, when you create it. Store it somewhere safe, like a password manager, as you will not be able to see it again.

All your access tokens are listed on your profile page, along with their status. From there you can revoke a token, if it is no longer needed or if you are worried that the secret was accidentally disclosed.

You can also renew a token from your profile page. This is useful when a token expires after six months. Renewing a token will change the underlying secret, so you will need to update any environment variables where the token gets passed through to scripts.

Using environment variables

Any examples in the API documentation will assume you have RISKSCAPE_TOKEN set as an environment variable. On Linux/Mac, you can set an environment variable for your terminal session like this:

read -s -p "Access token: " RISKSCAPE_TOKEN
export RISKSCAPE_TOKEN

On Windows PowerShell, you could use:

$env:RISKSCAPE_TOKEN = Read-Host -MaskInput "Access token"

Note

Using an environment variable like this is a simple way to avoid accidentally exposing your tokens. The read command avoids the token appearing in your bash command history.

Feed tokens

By default, personal API tokens grant the same read/write access to the RiskScape Platform that your user account has. In future, you may be able to limit the scope of a personal access token, e.g. read-only or project-scope. However, if your script or external tool only needs to access model results, then a useful alternative is to use API feed tokens.

A RiskScape Platform feed only contains model results for a single Platform project. The feed token only grants read-only access to these selected model results, so it is much more limited in scope than a personal access token.

Token access summary

The following table summarizes the different access tokens and what they grant access to in the RiskScape Platform.

Access permission	Personal API token	WebDAV token	Feed token
Project storage (i.e. input data)	✔	✔
Personal storage (i.e. input data)	✔	✔
All model results (for all your projects)	✔
Curated model results (for only one project)	✔		✔
Read API access (e.g. view project members)	✔
Write API access (e.g. run models)	✔

Tip

Organization admin users could also potentially limit the scope of personal API tokens by creating dedicated user accounts that only belong to a single project, e.g. XYZ-dashboard-user.

Using an access token

An access token is sent as HTTP Basic authentication, with TOKEN as the username and the token as the password:

GET /api/projects
Authorization: Basic base64(TOKEN:your-access-token)

Most HTTP clients and libraries have a shorthand for this. For example, with curl:

curl -u TOKEN:your-access-token https://riskscape.nz/api/projects

Tip

The same access tokens work over WebDAV. See WebDAV.