Skip to main content

Authenticating to MotherDuck

MotherDuck supports two types of authentication:

  • Human users authentication, typically used by the MotherDuck UI
  • Authentication using a service token, more convenient for Python or CLI

Human User Authentication​

MotherDuck UI authenticates using several methods:

  • Google
  • Github
  • Username and password

You can leverage multiple modes of authentication in your account. For example, you can authenticate both via Google and via username and password as you see fit.

To authenticate in CLI or Python, human users will be redirected to an authentication web page. Currently, this happens every session. To avoid having to re-authenticate, you can save your service token - please read Authenticating With a Service Token for more information.

Authentication Using a Service Token​

If you are using Python or CLI and don’t want to authenticate every session, you can securely save your credentials locally.

Fetching the Service Token​

To fetch your service token:

  • Go to the MotherDuck UI
  • In top right click on gear icon ⚙️
  • Copy the “Service Token” to your clipboard

service token example

Using The Service Token to Connect​

You can use this token in the MotherDuck URL: motherduck:?motherduck_token=<token>. Optionally you can shorten to md . For example: md:?motherduck_token=<token>.

An example of using this syntax in Python:

# connecting to a MotherDuck database my_db directly
con=duckdb.connect('md:?motherduck_token=<token>')

Saving The Service Token As An Environment Variable​

If you’d like not to include the service token in-line in your code, you can save the service token as an environment variable.

An example of using this syntax in terminal:

export motherduck_token='<token>'

You can also add this line to your ~/.zprofile or ~/.bash_profile.

Once this is done, your authentication token is saved and you can simply connect to MotherDuck:

# connecting to MotherDuck without opening a local DuckDB database first
con=duckdb.connect('md:')

Authentication Using SaaS Mode​

You can limit MotherDuck's ability to interact with your local environment using SaaS Mode:

  • Disable reading or writing local files
  • Disable reading or writing local DuckDB databases
  • Disable installing or loading any DuckDB extensions locally
  • Disable changing any DuckDB configurations locally

This mode is useful for third-party tools, such as BI vendors, that host DuckDB themselves and require additional security controls to protect their environments.

Syntax​

.open md:[<database_name>]?[motherduck_token=<motherduck_token>]&saas_mode=true

Notes:

  • <database_name> will be created if it doesn't exist already
  • <database_name> that starts with a number cannot be connected to directly. You will need to connect without a database specified and then CREATE and USE using a double quoted name. Eg: USE DATABASE "1database"

Example Usage​

.open md:?saas_mode=true