API keys / tokens

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

When using the Nominal client library, there are two primary ways of authenticating:

Storing credentials to disk

First, run the following in your terminal and follow on-screen prompts to insert the base_url and API key:

$ $ python -m nominal auth set-token
> 
> # Alternatively, use the globally installed CLI
> $ nom auth set-token

This will store your API key in a config file ~/.nominal.yml. The API key will automatically be used when using the client again.

1 import nominal
2 
3 # Simply grab the "default" client using your stored credentials
4 client = nominal.get_default_client()
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())

Directly using credentials in your scripts

1 import nominal
2 
3 # Set login details for the user
4 nominal.set_token("<insert api key>")
5 
6 # Get an instance of the client using provided credentials
7 client = nominal.get_default_client()
8 
9 # Get details about the currently logged-in user to validate authentication
10 # Will display an object like: `User(display_name='your_email@your_company.com', ...)`
11 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.