Skip to content

Client

Authentication

TheHive API provides two ways to authenticate the client:

  • apikey auth
  • username and password auth

Auth with apikey

from thehive4py import TheHiveApi

hive = TheHiveApi(
    url="http://localhost:9000",
    apikey="h1v3b33",
)

Auth with username and password

from thehive4py import TheHiveApi

hive = TheHiveApi(
    url="http://localhost:9000",
    username="analyst@thehive",
    password="h1v3b33",
)

Organisation

The client will use the default organisation of the user. However in case the user belongs to multiple organisation the client also provides options to specify which organisation to use.

Specify the organisation during init

In this example we will instaniate a client with the admin organisation explicitly:

from thehive4py import TheHiveApi

client_with_organisation = TheHiveApi(
    url="http://localhost:9000",
    apikey="h1v3b33",
    organisation="admin",
)

Switch organisations during runtime

In this example we will instantiate a client without explicitly specifying an organisation and switch to another organisation using the session_organisation property:

from thehive4py import TheHiveApi

hive = TheHiveApi(
    url="http://localhost:9000",
    apikey="h1v3b33",
)

hive.session_organisation = "other-org"

Warning

The session_organisation property is not thread-safe and it's almost always better to instantiate more clients if one wants to work with multiple organisations in parallel.

SSL Verification

By default the client verifies if the connection is going through SSL. In case one needs to pass a custom certificate bundle or directory it's possible via the verify argument like:

from thehive4py import TheHiveApi

hive = TheHiveApi(
    url="http://localhost:9000",
    apikey="h1v3b33",
    verify="/etc/ssl/certs/ca-certificates.crt",
)

Note

It's also possible to disable SSL verification completely by setting verify to False. However this is greatly discouraged as it's a security bad practice.

Retries

The client comes with a sensible retry mechanism by default that will try to cover the most common use cases. However it's also possible to configure a tailored retry mechanism via the max_retries argument.

The below example will configure a custom retry mechanism with 5 total attempts, a backoff factor of 0.3 seconds on GET methods and 500 status codes: 

from urllib3 import Retry

from thehive4py import TheHiveApi

simple_retries = Retry(
    total=5,
    backoff_factor=0.5,
    allowed_methods=["GET"],
    status_forcelist=[500],
)

hive = TheHiveApi(
    url="http://localhost:9000",
    apikey="h1v3b33",
    max_retries=simple_retries,
)

To learn more about the urllib3.Retry object please consult the official documentation here.