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 access_token: str | None = None#: Authenticate with a pre-issued OIDC access token (e.g. CI federated JWT exchange).

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, offline_token, or access_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 and automated workflows.

For CI pipelines that obtain a short-lived token via OIDC (for example, GitHub Actions federated with Keycloak), prefer Access tokens instead.

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

Note

You cannot combine credentials and offline_token. See Access tokens for the third non-interactive authentication option.

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")

Access tokens#

Pre-issued access tokens are short-lived OIDC bearer tokens. They are suited to CI/CD pipelines where an external step (for example, GitHub Actions OIDC exchanged with Keycloak) already obtained a token. Unlike offline_token, access tokens are not refreshed by the SDK: when they expire, obtain a new token from your CI login step.

Using an access token#

Pass the token explicitly when creating the client:

import ansys.simai.core as asc

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

Or set the SIMAI_ACCESS_TOKEN environment variable (useful in CI):

import ansys.simai.core as asc

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

Warning

Do not commit access tokens to source control or configuration files. Prefer SIMAI_ACCESS_TOKEN in CI secrets or ephemeral job environment variables.

Note

You cannot combine credentials, offline_token, and access_token. Choose one authentication method.