Authentication

In order to interact with most DagsHub features you need to authenticate using a user token.

For basic every day use cases no specific setup is required, the client will prompt you to authenticate via OAuth if there were no valid tokens found. The functions on this page are only relevant for advanced use cases and/or CI environments.

Using a long lived app token

You can generate a long lived app token with no expiry date from your User Settings.

After generating it, you can make the client use it by doing any of the following:

  • Setting the DAGSHUB_USER_TOKEN environment variable to the value of the token.

  • Using a CLI command dagshub login --token <token>. This will store the token in the token cache.

  • Calling the add_app_token() function. This will store the token in the token cache.

dagshub.auth.add_app_token(token: str, host: str | None = None, **kwargs)

Adds an application token to the token cache. This is a long-lived token that you can add/revoke in your profile settings on DagsHub.

Parameters:

  • token – Token value

  • host – URL of the hosted DagsHub instance. Leave empty to use the default https://dagshub.com.

Keyword Arguments:

cache_location – Path to an alternative cache location. You can override the default cache location to be used by the client by setting the DAGSHUB_CLIENT_TOKENS_CACHE environment variable.

Note

App tokens are always prioritized over OAuth tokens when using get_token() and get_authenticator().

Getting a token for use in other places

dagshub.auth.get_token(**kwargs) → str

Gets a DagsHub token in regular string form.

Use this function when you want to, for example, manually authenticate with DagsHub’s MLflow using MLFLOW_TRACKING_PASSWORD.

If no valid token was found and fail_if_no_token wasn’t set to True, triggers OAuth flow.

Keyword Arguments:

  • fail_if_no_token – Whether to get an OAuth token if no valid token was found in cache initially. If set to True, raises a RuntimeError. If set to False (default), launches the OAuth flow.

  • cache_location – Path to an alternative cache location. You can override the default cache location to be used by the client by setting the DAGSHUB_CLIENT_TOKENS_CACHE environment variable.

  • host – URL of the hosted DagsHub instance. default is https://dagshub.com.

dagshub.auth.get_authenticator(**kwargs) → DagshubAuthenticator

Get an authenticator object that can be used to authenticate a request to DagsHub using an http library like httpx or requests.

When used with httpx, the authenticator has renegotiation logic. That means that if DagsHub rejects a token, the authenticator will try to get another token from the cache, or fall back to OAuth.

If no valid token was found and fail_if_no_token wasn’t set to True, triggers OAuth flow.

Keyword Arguments:

  • fail_if_no_token – Whether to get an OAuth token if no valid token was found in cache initially. If set to True, raises a RuntimeError. If set to False (default), launches the OAuth flow.

  • cache_location – Path to an alternative cache location. You can override the default cache location to be used by the client by setting the DAGSHUB_CLIENT_TOKENS_CACHE environment variable.

  • host – URL of the hosted DagsHub instance. default is https://dagshub.com.

Triggering the OAuth flow explicitly

dagshub.auth.add_oauth_token(host: str | None = None, referrer: str | None = None, **kwargs)

Launches the OAuth flow that generates a short-lived token.

Note

This will open a new browser window, so this is not a CI/headless friendly function. Consider using add_app_token() or setting the DAGSHUB_USER_TOKEN env var in those cases.

Parameters:

  • host – URL of the hosted DagsHub instance. Leave empty to use the default https://dagshub.com.

  • referrer – For custom referral flows

Keyword Arguments:

cache_location – Path to an alternative cache location. You can override the default cache location to be used by the client by setting the DAGSHUB_CLIENT_TOKENS_CACHE environment variable.

You can also trigger the OAuth flow by doing dagshub login in CLI.

Clearing the token cache

dagshub.auth.clear_token_cache(force=False)

Clear the token cache file.

Warning

This will remove ALL tokens you have stored for any dagshub instance you connected to.

Connecting to a hosted DagsHub instance

If you are a self-serve customer of DagsHub, set DAGSHUB_CLIENT_HOST environment variable to the url of the DagsHub deployment. All client functions will automatically connect to the hosted instance.