Skip to main content

aip_sdk.init

aip_sdk.init(base_url: str | None = None, *, username: str | None = None, password: str | None = None, api_key: str | None = None, impersonate_user_id: str | None = None, token: str | None = None, workspace_id: str | None = None, user_id: str | None = None) -> APIClient

Configure the default AIP connection for this Python session.

Call this once at the top of your script (or notebook) before using any API-backed operations. All subsequent Project.create(), Project.get(), project.upload_dataset(), etc. calls will reuse this connection.

There are two credentials, and they are not interchangeable. A JWT (token) is short-lived — it expires roughly half a day after it is issued, and this SDK never refreshes it, so a script holding one starts failing with an authentication error mid-run once it expires. An API key (api_key) is long-lived and does not expire on its own. Prefer username + password (re-exchanged on every init()) or api_key for unattended or long-running work; reach for token only for a short interactive session or when a secrets manager already hands you one.

Auth precedence (highest to lowest):

  1. token — use an existing JWT directly.
  2. username + password — exchange for a JWT via POST /auth/token (recommended for interactive scripts and notebooks). Falls back to AIP_USERNAME (or older AIP_EMAIL) + AIP_PASSWORD env vars or ~/.aip/config.
  3. api_key — x-api-key header (CI/CD pipelines with a pre-issued key). Falls back to AIP_API_KEY env var or ~/.aip/config.

Parameters

  • base_url str | None: Base URL of the running aip-api service. Defaults to the value resolved by get_config() (AIP_API_URL env var / ~/.aip/config / http://localhost:8010).
  • username str | None: User username for JWT login (auto-exchanges for a token).
  • password str | None: User password for JWT login.
  • api_key str | None: Long-lived API key, sent as the x-api-key header when no token is configured.
  • impersonate_user_id str | None: Admin-only override that scopes every call to another user's data, sent as the x-user-id header. Not needed for ordinary use: a non-admin credential is always scoped to its own user, and the override is ignored. Also readable via the AIP_IMPERSONATE_USER_ID env var.
  • token str | None: Pre-obtained JWT Bearer token. Short-lived and never refreshed — see the note above.
  • workspace_id str | None: Default workspace ID. When set, Project.create() uses it automatically so callers don't have to pass workspace_id on every call. Also readable via AIP_WORKSPACE_ID env var or ~/.aip/config.
  • user_id str | None: Deprecated alias for impersonate_user_id. Passing it emits a DeprecationWarning; it will be removed in a future release.

The credentials are verified before this returns, and a one-line confirmation naming the user, base URL, workspace, and admin flag is logged at INFO. A workspace is auto-selected only for a non-admin caller who did not name one: a platform administrator can see every workspace, so no default is guessed on their behalf.

Returns

Raises

  • AuthError: If the resolved credentials are missing, invalid, or expired.
  • APIError: On any other HTTP error while verifying them.

Examples:

import aip_sdk as aip

# Recommended: username + password — one call, JWT issued automatically
aip.init("http://localhost:8010", username="alice@example.com", password="s3cr3t", workspace_id="ws-abc123")

# CI/CD and other unattended jobs: a long-lived, pre-issued API key
aip.init("http://localhost:8010", api_key="TOKEN-ci")

# A JWT you already hold (e.g. from a secrets manager) — expires; not refreshed
aip.init("http://localhost:8010", token=os.environ["AIP_TOKEN"])

# Platform admin acting on another user's data
aip.init("http://localhost:8010", api_key="TOKEN-admin", impersonate_user_id="u-abc123")

# Read everything from environment variables / ~/.aip/config
aip.init()