Authentication

To access the Nominal platform via its API or the command-line interface requires a system generated password called an API key. Setting an API key is the first step in any programmatic workflow.

For historic reasons, there exists a variant of an API key called a Personal access token. These API keys are short lived and meant for quick, one-off experiments—but are otherwise identical in function.

Generating an API key

API keys are generated from the profile page:

Click API keys → Generate API key. Give the key a name and an expiry date, and click Generate key. Copy the key: you won’t be able to see it again.

As noted above, Personal access tokens are short-lived API keys, aimed at quick experimentation (<24 hours). To generate one of these, click Personal access tokens → Copy access token. The token is copied to the clipboard.

Using the API key

Concepts

Base URL: The URL through which the Nominal API is accessed (typically https://api.gov.nominal.io/api).
Workspace: A mechanism by which to isolate datasets; each user has one or more workspace, and data in one cannot be seen from another. Note that one token may access multiple workspaces.
Profile: A combination of base URL, API key, and workspace.

There are two primary ways of authenticating the Nominal Client. The first is to use a profile stored on disk, and the second is to use a token directly.

Storing credentials to disk

Run the following in a terminal and follow on-screen prompts to set up a connection profile:

$ $ nom config profile add default
> 
> # Alternatively, if `nom` is missing from the path:
> $ python -m nominal config profile add default

Here, “default” can be any name chosen to represent this profile (reminder: a profile represents a base URL, API key, and workspace).

The profile will be stored in ~/.config/nominal/config.yml, and can then be used to create a client:

1 from nominal.core import NominalClient
2 
3 client = NominalClient.from_profile("default")
4 
5 # Get details about the currently logged-in user to validate authentication
6 # Will display an object like: `User(display_name='your_email@your_company.com', ...)`
7 print(client.get_user())

If you have previously used nom to store credentials, prior to the availability of profiles, you will need to migrate your old configuration file (~/.nominal.yml) to the new format (~/.config/nominal/config.yml).

You can do this with the following command:

$ nom config migrate
> 
> # Or, if `nom` is missing from your path:
> python -m nominal config migrate

Directly using credentials in your scripts

1 from nominal.core import NominalClient
2 
3 # Get an instance of the client using provided credentials
4 client = NominalClient.from_token("<insert api key>")
5 
6 # Get details about the currently logged-in user to validate authentication
7 # Will display an object like: `User(display_name='your_email@your_company.com', ...)`
8 print(client.get_user())

NOTE: you should never share your Nominal API key with anyone. We therefore recommend that you not save it in your code and/or scripts.

If you trust the computer you are on, use nom to store the credential to disk.
Otherwise, use a password manager such as 1password or bitwarden to keep your token safe.

If you’re not sure whether your company has a Nominal tenant, please reach out to us.

Rate limits

API calls are rate limited to prevent abuse and protect the system from denial-of-service attacks. These are grouped by token, and allow for a maximum of:

100 concurrent requests, and
20 requests/second.