login#

teamworksams.login_main.login(url: str, username: str | None = None, password: str | None = None, option: LoginOption | None = None) → Dict[str, Any][source]#

Authenticate with an AMS instance and return session details.

Establishes a session with the AMS API using provided credentials, returning a dictionary with login data, session header, and cookie. Initializes a AMSClient that is cached for reuse by other functions (e.g., teamworksams.user_main.get_user()) when option.cache=True. Useful for verifying credentials or accessing session details for custom API calls. See Managing Credentials, Authentication, and Caching for authentication workflows.

Parameters:

  • url (str) – The AMS instance URL (e.g., ‘https://example.smartabase.com/site’). Must include a valid site name.

  • username (Optional[str]) – Username for authentication. If None, uses AMS_USERNAME or keyring credentials. Defaults to None.

  • password (Optional[str]) – Password for authentication. If None, uses AMS_PASSWORD or keyring credentials. Defaults to None.

  • option (LoginOption, optional) – Configuration options, including interactive_mode for status messages (e.g., “Successfully logged in”) and cache for client reuse. Defaults to None (uses default LoginOption with interactive_mode=True, cache=True).

Returns:

A dictionary containing:

  • ’login_data’: The JSON response from the login API, including user details (e.g., user ID, application ID).

  • ’session_header’: The session header from the response headers, used for subsequent API calls.

  • ’cookie’: The formatted cookie string (e.g., ‘JSESSIONID=session_header’).

Return type:

Dict[str, Any]

Raises:

teamworksams.utils.AMSError – If the URL is invalid, credentials are missing or invalid, the login request fails (e.g., HTTP 401), or the session header is not provided.

Examples

>>> from teamworksams import login, LoginOption
>>> login_result = login(
...     url = "https://example.smartabase.com/site",
...     username = "user",
...     password = "pass",
...     option = LoginOption(interactive_mode=True, cache=True)
... )
ℹ Logging user into https://example.smartabase.com/site...
✔ Successfully logged user into https://example.smartabase.com/site.
>>> print(login_result.keys())
dict_keys(['login_data', 'session_header', 'cookie'])
>>> print(login_result['cookie'])
JSESSIONID=abc123

Additional Notes#

  • The returned dictionary includes a ‘session_header’ and ‘cookie’ for use in custom API calls with a AMSClient().

  • Use option.interactive_mode=True to display status messages, helpful for debugging or interactive scripts.

  • If credentials are not provided, the function checks AMS_USERNAME, AMS_PASSWORD, or keyring credentials.

See Also#