Skip to content

Client

airt.client.Client

A class for authenticating and accessing the airt service.

To access the airt service, you must create a developer account. Please contact us by email info@airt.ai to get one.

Upon successful verification, you will receive the username/password for the developer account in an email.

Finally, you need an application token to access all the APIs in airt service. Please call the get_token method with the username/password to get one. You can either pass the username, password, and server address as parameters to the get_token method or store the same in the AIRT_SERVICE_USERNAME, AIRT_SERVICE_PASSWORD, and AIRT_SERVER_URL environment variables.

Upon successful authentication, the airt services will be available to access.

As an additional layer of security, we also support Multi-Factor Authentication (MFA) and Single sign-on (SSO) for generating tokens.

Multi-Factor Authentication (MFA) can be used to help protect your account from unauthorized access by requiring you to enter an additional code when you request a new token.

Once authenticated successfully, activating MFA for your account is a simple two step process:

  1. Enable MFA for your account by calling User.enable_mfa method which will generate a QR code. You can then use an authenticator app, such as Google Authenticator to scan the QR code.

  2. Activate the MFA by calling User.activate_mfa method and passing the dynamically generated six-digit verification code from the authenticator app.

Once MFA is successfully activated, you need to pass the dynamically generated six-digit verification code along with the username/password to get_token method for generating new tokens.

Once authenticated successfully, you can also enable Single sign-on (SSO) for your account. Currently, we support only Google and Github as the external authentication providers (SSO). More authentication providers will be supported in the upcoming releases.

Authenticating using Single sign-on (SSO) is also a three-step process:

  1. Enable the SSO provider by calling the User.enable_sso method with a valid SSO provider and an email address.

  2. To get the token, you must have to complete the SSO authentication with the provider. Calling the Client.get_token method with a valid SSO provider will give you an authorization URL. Please copy and paste it into your preferred browser and initiate the authentication and authorization process with the SSO provider.

  3. Once the authentication is successful, calling the Client.set_sso_token method gets a new developer token and will implicitly use in all the interactions with the airt server.

get_token(*, username=None, password=None, server=None, sso_provider=None, otp=None) classmethod

Get application token for airt service from a username/password pair.

This methods validates the developer credentials and returns an auth token. The returned auth token is implicitly used in all the interactions with the server.

In case the token is requested using Single sign-on (SSO), then an authorization URL will be returned to the user.

The user must have to complete the authentication from the external SSO provider within 10 minutes. Else the SSO login will be a timeout and the user have to request the token again.

In case of MFA enabled user, along with the username/password the dynamically generated six-digit verification code also needs to be passed when requesting an auth token.

Parameters:

Name Type Description Default
username str

Username for the developer account. If None (default value), then the value from AIRT_SERVICE_USERNAME environment variable is used.

None
password str

Password for the developer account. If None (default value), then the value from AIRT_SERVICE_PASSWORD environment variable is used.

None
server str

The airt server uri. If None (default value), then the value from AIRT_SERVER_URL environment variable is used. If the variable is not set as well, then the default public server will be used. Please leave this setting to default unless you are running the service in your own server (please email us to info@airt.ai for that possibility).

None
sso_provider Optional[str]

Name of the Single sign-on (SSO) provider. Please pass this parameter only if you have successfully enabled SSO for this provider.

None
otp Optional[str]

Dynamically generated six-digit verification code from the authenticator app.

None

Returns:

Type Description
Optional[str]

The authorization url if the token is requested using Single sign-on (SSO).

Exceptions:

Type Description
ValueError

If the username/password pair does not match.

ConnectionError

If the server address is invalid or not reachable.

KeyError

If username/password is neither passed as parameters nor stored in environment variables.

Source code in airt/client.py
@classmethod
def get_token(  # type: ignore
    cls,
    *,
    username: str = None,
    password: str = None,
    server: str = None,
    sso_provider: Optional[str] = None,
    otp: Optional[str] = None,
) -> Optional[str]:
    """Get application token for airt service from a username/password pair.

    This methods validates the developer credentials and returns an auth token. The returned auth
    token is implicitly used in all the interactions with the server.

    In case the token is requested using Single sign-on (SSO), then an authorization URL will be
    returned to the user.

    The user must have to complete the authentication from the external SSO provider within 10
    minutes. Else the SSO login will be a timeout and the user have to request the token again.

    In case of MFA enabled user, along with the username/password the dynamically generated
    six-digit verification code also needs to be passed when requesting an auth token.

    Args:
        username: Username for the developer account. If None (default value), then the value from
            **AIRT_SERVICE_USERNAME** environment variable is used.
        password: Password for the developer account. If None (default value), then the value from
            **AIRT_SERVICE_PASSWORD** environment variable is used.
        server: The airt server uri. If None (default value), then the value from **AIRT_SERVER_URL** environment variable
            is used. If the variable is not set as well, then the default public server will be used. Please leave this
            setting to default unless you are running the service in your own server (please email us to info@airt.ai
            for that possibility).
        sso_provider: Name of the Single sign-on (SSO) provider. Please pass this parameter only if you have successfully
            enabled SSO for this provider.
        otp: Dynamically generated six-digit verification code from the authenticator app.

    Returns:
        The authorization url if the token is requested using Single sign-on (SSO).

    Raises:
        ValueError: If the username/password pair does not match.
        ConnectionError: If the server address is invalid or not reachable.
        KeyError: If username/password is neither passed as parameters nor stored in environment variables.
    """
    cls.server = get_base_url(server)

    username, password = _get_credentials(username, password)

    if otp is not None:
        password = json.dumps({"password": password, "user_otp": otp})

    if sso_provider is None:
        response = post_data(
            url=f"{cls.server}/token",
            data=dict(username=username, password=password),
            token=None,
        )

        cls.auth_token = response["access_token"]
    else:
        response = post_data(
            url=f"{cls.server}/sso/initiate",
            data=json.dumps(  # type: ignore
                dict(
                    username=username, password=password, sso_provider=sso_provider
                )
            ),
            token=None,
        )

        cls.sso_authorization_url = response["authorization_url"]
        return cls.sso_authorization_url

set_sso_token() classmethod

Set the application token generated using Single sign-on (SSO).

The token set using this method will be implicitly used in all the interactions with the server.

Please call this method only if you successfully enabled and completed the login with the Single sign-on (SSO) provider. If not, please call the get_token method with an appropriate sso_provider to initiate the SSO authentication.

Source code in airt/client.py
@classmethod
def set_sso_token(cls):
    """Set the application token generated using Single sign-on (SSO).

    The token set using this method will be implicitly used in all the interactions with the server.

    Please call this method only if you successfully enabled and completed the login with the Single
    sign-on (SSO) provider. If not, please call the `get_token` method with an appropriate
    sso_provider to initiate the SSO authentication.
    """
    quoted_authorization_url = urllib.parse.quote(cls.sso_authorization_url)
    response = get_data(
        url=f"{cls.server}/sso/token/?authorization_url={quoted_authorization_url}",
        token=None,
    )

    cls.auth_token = response["access_token"]

set_token(token=None, server=None) classmethod

Set application token for airt service.

The token set using this method will be implicitly used in all the interactions with the server.

Please call this method only if you already have a token. If not, please call the get_token method to generate one.

Parameters:

Name Type Description Default
token str

The application token generated from a username/password pair. If None (default value), then the value from AIRT_SERVICE_TOKEN environment variable is used.

None
server str

The airt server uri. If None (default value), then the value from AIRT_SERVER_URL environment variable is used. If the variable is not set as well, then the default public server will be used. Please leave this setting to default unless you are running the service in your own server (please email us to info@airt.ai for that possibility).

None

An example to set the token:

Client.set_token()
Source code in airt/client.py
@classmethod
def set_token(cls, token: str = None, server: str = None):
    """Set application token for airt service.

    The token set using this method will be implicitly used in all the interactions with the server.

    Please call this method only if you already have a token. If not, please call the `get_token` method to generate one.

    Args:
        token: The application token generated from a username/password pair. If None (default value), then the value from
            **AIRT_SERVICE_TOKEN** environment variable is used.
        server: The airt server uri. If None (default value), then the value from **AIRT_SERVER_URL** environment variable
            is used. If the variable is not set as well, then the default public server will be used. Please leave this
            setting to default unless you are running the service in your own server (please email us to info@airt.ai
            for that possibility).

    An example to set the token:

    ```python
    Client.set_token()
    ```
    """

    auth_token = token if token is not None else os.environ.get(SERVICE_TOKEN)

    if not auth_token:
        raise KeyError(
            f"The token is neither passed as parameter nor set in the environment variable {SERVICE_TOKEN}."
        )

    cls.auth_token = auth_token
    cls.server = get_base_url(server)

version() staticmethod

Return the client and server versions.

Returns:

Type Description
dict

A dict containing the client and server versions.

Exceptions:

Type Description
ConnectionError

If the server address is invalid or not reachable.

An example to get the client and server versions:

Client.version()
Source code in airt/client.py
@staticmethod
def version() -> dict:
    """Return the client and server versions.

    Returns:
        A dict containing the client and server versions.

    Raises:
        ConnectionError: If the server address is invalid or not reachable.

    An example to get the client and server versions:

    ```python
    Client.version()
    ```
    """

    response = Client._get_data(relative_url=f"/version")

    version = {
        # nosemgrep: python.lang.security.audit.non-literal-import.non-literal-import
        "client": importlib.import_module(CLIENT_NAME).__version__,
        "server": response["airt_service"],
    }

    return version
Back to top