class igwn_auth_utils.Session(token=None, token_audience=None, token_scope=None, token_issuer=None, cert=None, auth=None, url=None, force_noauth=False, fail_if_noauth=False, **kwargs)[source]

requests.Session class with default IGWN authorization handling.

Discovery/configuration of authorisation/authentication methods is attempted in the following order:

  1. if force_noauth=True is given, no auth is configured;

  2. for SciTokens:

    1. if a bearer token is provided via the token keyword argument, then use that, or

    2. look for a bearer token by passing the token_audience and token_scope keyword parameters to igwn_auth_utils.find_scitokens();

  3. for X.509 credentials:

    1. if an X.509 credential path is provided via the cert keyword argument, then use that, or

    2. look for an X.509 credential using igwn_auth_utils.find_x509_credential()

  4. for basic auth (username/password):

    1. if auth keyword is provided, then use that, or

    2. read the netrc file located at ~/.netrc, or at the path stored in the $NETRC environment variable, and look for a username and password matching the hostname given in the url keyword argument;

  5. if none of the above yield a credential, and fail_if_noauth=True was provided, raise a ValueError.

Steps 2 and 3 are all tried independently, with all valid credentials (one per type) configured for the session. Only when SciTokens are disabled (token=False), will step 4 will be tried to configure basic username/password auth. It is up to the request receiver to handle the multiple credential types and prioritise between them.


Bearer token (scitoken) input, one of

  • a bearer token (scitokens.SciToken),

  • a serialised token (str, bytes),

  • False: disable using tokens completely

  • True: discover a valid token via igwn_auth_utils.find_scitoken() and error if something goes wrong

  • None: try and discover a valid token, but try something else if that fails


The value(s) of the audience (aud) claim to pass to igwn_auth_utils.find_scitoken() when discovering available tokens.


The value(s) of the scope to pass to igwn_auth_utils.find_scitoken() when discovering available tokens.


The value of the issuer (iss) claim to pass to igwn_auth_utils.find_scitoken() when discovering available tokens.


X.509 credential input, one of


(username, password) tuple or other authentication/authorization object to attach to a Request. By default a new HTTPSciTokenAuth handler will be attached to configure Authorization headers for each request.


the URL/host that will be queried within this session; this is used to set the default token_audience and to access credentials via safe_netrc.


Disable the use of any authorisation credentials (mainly for testing).


Raise a IgwnAuthError if no authorisation credentials are presented or discovered.

raise_for_status : bool, optional

If True (default), automatically call raise_for_status() after receiving any response.


IgwnAuthError – If cert=True or token=True is given and the relevant credential was not actually discovered, or if fail_if_noauth=True is given and no authorisation token/credentials of any valid type are presented or discovered.

See also


for details of the standard options


for details of the SciToken discovery


for details of the X.509 credential discovery


To use the default authorisation discovery:

>>> from igwn_auth_utils.requests import Session
>>> with Session() as sess:
...     sess.get("")

To explicitly pass a specific SciToken as the token:

>>> with Session(token=mytoken) as sess:
...     sess.get("")

To explicitly require that a token is discovered, and disable any X.509 discovery:

>>> with Session(token=True, x509=False) as sess:
...     sess.get("")

To use default authorisation discovery, but fail if no credentials are discovered:

>>> with Session(fail_if_noauth=True) as sess:
...     sess.get("")

To disable all authorisation discovery:

>>> with Session(force_noauth=True) as sess:
...     sess.get("")