Credentials

The GPP Client supports multiple sources for authentication. This page explains how the client determines which token and which environment to use at runtime.

Most users only need to set a token once, either through environment variables or via the configuration file. Advanced configuration options are documented in Config.

Overview

Credential resolution is performed by CredentialResolver. The resolver determines:

  • Which environment to use

  • Which token to use

  • The correct GraphQL URL for that environment

The resolution follows a strict priority order.

Resolution Priority

The following table summarizes how credentials are resolved, highest priority first:

  1. Explicit arguments passed to GPPClient

  2. Environment variables (if enabled in config)

  3. Configuration file stored on disk

If no valid token can be found, a GPPAuthError is raised.

Priority 1: Explicit Arguments

The highest priority is arguments provided directly when constructing the client.

from gpp_client import GPPClient
from gpp_client import GPPEnvironment

client = GPPClient(env=GPPEnvironment.STAGING, token="abc123")

If env or token is provided explicitly, they override all other sources.

Priority 2: Environment Variables

If explicit arguments are not provided and environment variables are enabled (see disable_env_vars in the configuration file), the resolver checks for:

Environment selector:

  • GPP_ENV

Token variables (per environment):

  • GPP_DEVELOPMENT_TOKEN

  • GPP_STAGING_TOKEN

  • GPP_PRODUCTION_TOKEN

Generic fallback token:

  • GPP_TOKEN

Examples:

export GPP_ENV="STAGING"
export GPP_STAGING_TOKEN="staging-token-value"

When these are present, they override the configuration file.

Priority 3: Local Configuration File

If neither explicit arguments nor environment variables provide credentials, the resolver uses the local configuration file managed by GPPConfig.

Location:

  • POSIX: ~/.gpp-client/config.toml

  • Windows: %APPDATA%/GPP Client/config.toml

Example:

env = "PRODUCTION"
disable_env_vars = false

[tokens]
DEVELOPMENT = ""
STAGING = ""
PRODUCTION = "my-prod-token"

Disabling Environment Variables

Users may disable the use of environment variables entirely:

from gpp_client import GPPConfig

config = GPPConfig()
config.disable_env_vars(save=True)

When disabled, the resolver will skip all environment variable lookups.

Full Resolution Example

from gpp_client.credentials import CredentialResolver

url, token, env = CredentialResolver.resolve()

print(env)     # GPPEnvironment.PRODUCTION
print(url)     # default production GraphQL URL
print(token)   # token resolved from args/env/config

Internals

The credential system uses two internal helper components:

Environment Variable Reader

class gpp_client.credentials.env_var_reader.EnvVarReader[source]

Bases: object

Reader for GPP client environment variables.

static get_env() → GPPEnvironment | None[source]

Get the GPP environment from environment variables.

Returns:

The GPP environment if set, else None.

Return type:

GPPEnvironment | None

static get_env_token(env: GPPEnvironment) → str | None[source]

Get the token for a specific environment from environment variables.

Parameters:

env (GPPEnvironment | str) – The GPP environment to get the token for.

Returns:

The token if found, else None.

Return type:

str | None

static get_token() → str | None[source]

Get the generic GPP token from environment variables.

Returns:

The generic token if found, else None.

Return type:

str | None

Credential Resolver

class gpp_client.credentials.CredentialResolver[source]

Bases: object

Resolves the effective GPP credentials to use based on priority.

Priority order (high to low): 1. Explicit arguments 2. Environment variables (if enabled) 3. Configuration file

static resolve(*, env: GPPEnvironment | None = None, token: str | None = None, config: GPPConfig | None = None) → tuple[str, str, GPPEnvironment][source]

Resolve the effective GPP URL, token, and environment.

Parameters:

  • env (GPPEnvironment | None, optional) – Optional explicit environment override.

  • token (str | None, optional) – Optional explicit token override.

  • config (GPPConfig | None, optional) – Optional GPPConfig instance. If None, a new instance will be created and loaded if the configuration file exists.

Returns:

A tuple containing (URL, token, environment).

Return type:

tuple[str, str, GPPEnvironment]

Raises:

GPPAuthError – If no valid token could be resolved.

static resolve_env(*, env: GPPEnvironment | None = None, config: GPPConfig | None = None) → GPPEnvironment[source]

Resolve the effective GPP environment to use.

Parameters:

  • env (GPPEnvironment | None, optional) – Optional explicit environment override.

  • config (GPPConfig | None, optional) – The GPPConfig instance, if not provided a new instance will be created.

Returns:

The resolved environment.

Return type:

GPPEnvironment

static resolve_token(*, env: GPPEnvironment, token: str | None = None, config: GPPConfig | None = None) → str[source]

Resolve the effective GPP token to use.

Parameters:

  • env (GPPEnvironment) – The GPP environment to resolve the token for.

  • token (str | None, optional) – Optional explicit token override.

  • config (GPPConfig | None, optional) – The GPPConfig instance, if not provided a new instance will be created.

Returns:

The resolved token.

Return type:

str

Raises:

GPPAuthError – If no valid token could be resolved.

Notes

  • Most users will interact with credentials through the CLI or configuration page.

  • Advanced users may override environments programmatically using env=....

  • Detailed configuration options are described in Config.