Installation and Setup

Installation¶

To install the Pixel API client, you can use pip to install the package from PyPI:

pip install pixel-client

Authentication¶

The client authenticates in one of two ways: with your Keycloak user credentials, or with a Pixel api key. Provide exactly one of the two - setting both raises a validation error.

Either way, the settings are defined in the PixelApiSettings class and can be passed directly, through env variables or through a .env file.

With user credentials¶

Set PIXEL_TENANT, PIXEL_USERNAME and PIXEL_PASSWORD:

from pixel_client import get_client, PixelApiSettings

# Get the client with the settings parsed from env variables
client = get_client()
# Get the async client with the settings parsed from env variables
client_async = get_client(async_=True)

# Get the client with the settings passed directly
settings = PixelApiSettings(
        PIXEL_TENANT=...,
        PIXEL_USERNAME=...,
        PIXEL_PASSWORD=...
    )
# Or from a .env file
settings = PixelApiSettings.from_env_file("my_env_file.env")
client = get_client(
    settings=settings
)
# Get the async client with the settings passed directly
client_async = get_client(
    settings=settings,
    async_=True
)

# subsequent calls to the get_client function will return the same client instances if the settings are the same

Reccomended approach is to use environment variables or a .env file to avoid hardcoding sensitive information in your codebase.

With an api key¶

An api key is a long lived token that acts on behalf of the user who created it. It has the project roles, groups or organisation-wide role it was given, and never more than that user's own current access. It suits unattended workloads - CI jobs, scheduled scripts, servers - where storing a username and password is not appropriate.

Set PIXEL_TENANT and PIXEL_API_KEY, and leave PIXEL_USERNAME / PIXEL_PASSWORD unset:

# .env
PIXEL_TENANT=my-tenant
PIXEL_API_KEY=pixel_v1_...

from pixel_client import get_client, PixelApiSettings

# From environment variables or a .env file
client = get_client()

# Or passed directly
settings = PixelApiSettings(
        PIXEL_TENANT=...,
        PIXEL_API_KEY=...
    )
client = get_client(settings=settings)

See Api keys for how to create, scope and revoke them.

Some calls need a signed-in user

A client authenticated with an api key can use the rest of the API within the key's access, but these calls need user credentials:

creating, listing, renaming, revoking and replacing api keys
creating and editing users (create_user, update_user)
creating, changing and deleting geo service users
the access views list_grants, get_user_access and get_group_access
me