Client configuration#

Where to start#

You start by creating a SimAIClient instance:

import ansys.simai.core as asc

simai_client = asc.SimAIClient(organization="my-company")

As demonstrated in the preceding code, you configure the instance by passing the required parameters on client creation. You are prompted for any missing parameters.

Once you understand how creating an instance works, you can look into using a configuration file for creating a client instance.

Configuration options#

Descriptions follow of all configuration options for the SimAIClient class:

pydantic model ClientConfig#

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

field credentials: Credentials | None = None#: Authenticate via username/password instead of the device authorization code.

field geomai_project: str | None = None#: Name of the GeomAI project to use by default.

field geomai_workspace: str | None = None#: Name of the GeomAI workspace to use by default.

field https_proxy: AnyHttpUrl | None = None#: URL of the HTTPS proxy to use.

field interactive: bool | None = True#: If True, it enables interaction with the terminal.

field no_sse_connection: bool = False#: Don’t receive live updates from the SimAI API.

field offline_token: str | None = None#: Authenticate via an offline token instead of credentials or device auth.

field organization: str = None#: Name of the organization(/company) that the user belongs to.

field project: str | None = None#: Name of the project to use by default.

field skip_version_check: bool = False#: Skip checking for updates.

field tls_ca_bundle: Literal['system', 'unsecure-none'] | PathLike | None = None#

Custom TLS CA certificate configuration. Possible values:

None: use secure defaults
"system": uses system CA certificates (python >= 3.10)
A PathLike object: use a custom CA
"unsecure-none": no TLS certificate validation

field url: HttpUrl = HttpUrl('https://api.simai.ansys.com/v2/')#: URL to the SimAI API.

field workspace: str | None = None#: Name of the workspace to use by default.

Credentials#

To use the SimAI API, your SimAIClient instance must be authenticated. By default, you are prompted to log in via your web browser. However, you can pass your credentials as parameters on client creation:

import ansys.simai.core as asc

simai_client = asc.SimAIClient(
    organization="company",
    credentials={
        # neither of these are required, but if they are missing you will be
        # prompted to input them
        "username": "user@company.com",
        "password": "hunter12",
    },
)

Credential options#

Descriptions follow of all credential options for the SimAIClient class:

pydantic model Credentials#

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

password (str)
totp (str | None)
username (str)

field password: str [Required]#: Password: Required if Credentials is defined, automatically prompted.

field totp: str | None = None#: One-time password: required if totp_enabled=True, automatically prompted.

field username: str [Required]#: Username: Required if Credentials is defined, automatically prompted.

Interactive mode#

When the property interactive is set to true, the users are prompted for the missing configuration properties. When the property is false, the interactive mode is turned off, and errors would be raised in case of missing configuration properties. Default behavior is interactive=true.

It is important to note that login through web browser is turned off when interactive=false. This means that either credentials or offline_token must be provided, otherwise an error would be raised.

Offline tokens#

Offline tokens are long-lived authentication tokens that can be used for non-interactive authentication. Unlike regular session tokens, offline tokens do not expire based on session timeouts, making them ideal for server-side scripts, CI/CD pipelines, and automated workflows.

Generating an offline token#

You can generate an offline token using an authenticated client:

import ansys.simai.core as asc

simai_client = asc.SimAIClient(organization="my-company")

token = simai_client.me.generate_offline_token()
print(f"Store this token securely: {token}")

Warning

Store your offline token securely. It provides full access to your account and should be treated like a password.

Using an offline token#

Once you have an offline token, you can use it for non-interactive authentication:

import ansys.simai.core as asc

simai_client = asc.SimAIClient(
    organization="my-company",
    offline_token="your-offline-token-here",
    interactive=False,
)

Or in a configuration file:

[default]
organization = "my-company"
offline_token = "your-offline-token-here"
interactive = false

Managing consents#

Consents are the authorization records that grant a client (like the SDK) permission to use offline tokens. You can list and revoke consents through the client:

# List all consents
consents = simai_client.me.consents.list()
for consent in consents:
    print(f"Client: {consent.client_id}, Created: {consent.created_date}")

# Revoke a specific consent (invalidates associated offline tokens)
simai_client.me.consents.revoke("sdk")

Note

You cannot use both credentials and offline_token at the same time. Choose one authentication method.