Authentication with Modelon Impact
This page explains how to authenticate and login to a Modelon Impact server from the Python client in various environments.
The cloud and on-premises Modelon Impact REST API for non-browser clients relies on an API key for authentication.
In order to work with the API, client code needs to pass impact-api-key: <api key>
header with all requests.
The Client() will initialize this header by default using the value of MODELON_IMPACT_CLIENT_API_KEY
environment variable.
The MODELON_IMPACT_CLIENT_API_KEY
environment variable is automatically set with a temporary user
specific API key inside the Modelon Impact environment. Therefore explicit user input is not needed
when the Python client is used in a script, notebook or custom function running within the Modelon Impact
by a logged in user.
The Python client could be easily initialized as follows for a user accessing the client library from inside Modelon Impact:
>>>> from modelon.impact.client import Client
>>>> client = Client()
The next session explains the process of generating and using API key when scripting with Python client from outside Modelon Impact, e.g., from a desktop.
Modelon Impact API key generation
An API key is needed for authentication in order to utilize the client with the Modelon Impact server.
To generate the key, go to the Server Management
on Modelon Impact. Click on the IMPACT API KEY
tab drop-down and click Regenerate and replace key
to generate a new one.
Remember that this is the only time you will see the secret. Make sure to store it safely.
Copy the key and keep it safe. If the key is lost or compromised, you can generate
a new one by clicking the Regenerate and replace key
button. This will delete
the old key, so any application that uses it must have their keys updated to work.
The API key is personal and each user may have one single key at a time,
so do not share one key between several persons.
The API key may be passed into the Client() constructor either via an environment variable, a key file or interactively.
1. Environment variable
The environment variable MODELON_IMPACT_CLIENT_API_KEY
can be set to contain the api_key
string value.
2. Credentials file
API key may be stored in a credentials file named api.key
located in the directory
~/.impact
in the users home folder. The client class will look for the key there if
the key is not set as an environment variable.
This file is also used by the client to store the key in interactive mode and might be overwritten, see interactive.
3. Interactive
The interactive mode is useful when running an interactive Python shell. Initialize the
client with the interactive
keyword set to True. If the environment variable is not
set and the credentials file does not exist you will be asked to enter the API key in a
prompt.
>>>> from modelon.impact.client import Client
>>>> client = Client(url=impact_url, interactive=True)
Enter API key:
When the key has been entered the first time, it will be stored in the credentials file to be used in future requests, and the prompt will not be shown again. If the key is changed, the file may be deleted which will cause the prompt to be shown again.
The stored API key can also be modified using the CredentialManager
class.
>>>> from modelon.impact.client.credential_manager import CredentialManager
>>>> credential_manager = CredentialManager()
>>>> credential_manager.get_key_from_file()
'some-old-api-key'
>>>> credential_manager.write_key_to_file('my-new-key')
>>>> credential_manager.get_key_from_file()
'my-new-key'
Note: The API key used to authenticate Modelon Impact is looked up in the following preference order:
API key saved in the environment variable -
MODELON_IMPACT_CLIENT_API_KEY
API key saved in the user’s
~/.impact/api.key
file.API key set via interactive prompt (if
interactive
is set to True)