Authentication

To use the Modal Client SDKs, you need to authenticate with Modal. There are two methods: interactive setup using the Modal CLI, or manual configuration using environment variables.

Method 1: Interactive setup (recommended)

The easiest way to authenticate is using the Modal CLI’s interactive setup:

Install the Python SDK

The Modal CLI is part of the Python SDK:

pip install modal

Run the setup command

Run the setup wizard to authenticate:

python3 -m modal setup

This will:

Open your browser to log in or create a Modal account
Generate API credentials
Save them to ~/.modal.toml

Verify authentication

Test that authentication is working:

Python
TypeScript
Go

import modal

client = modal.Client()
print("Authentication successful!")

import { ModalClient } from "modal";

const modal = new ModalClient();
console.log("Authentication successful!");

package main

import (
    "fmt"
    "log"
    
    modal "github.com/modal-labs/modal-client/go"
)

func main() {
    mc, err := modal.NewClient()
    if err != nil {
        log.Fatalf("Authentication failed: %v", err)
    }
    fmt.Println("Authentication successful!")
}

The configuration file is saved to ~/.modal.toml by default. You can customize this location using the MODAL_CONFIG_PATH environment variable.

Method 2: Environment variables

For automated environments, CI/CD pipelines, or production deployments, use environment variables:

Get your API credentials

A Token ID (starts with ak-)
A Token Secret (starts with as-)

Store your token secret securely. It will only be shown once and provides full access to your Modal account.

Set environment variables

Export the credentials as environment variables:

export MODAL_TOKEN_ID=ak-YOUR_TOKEN_ID_HERE
export MODAL_TOKEN_SECRET=as-YOUR_TOKEN_SECRET_HERE

For production, add these to your deployment environment or secrets manager.

Verify authentication

The SDKs will automatically detect and use these environment variables:

Python
TypeScript
Go

import modal

# Credentials are automatically loaded from environment variables
client = modal.Client()
print("Authentication successful!")

import { ModalClient } from "modal";

// Credentials are automatically loaded from environment variables
const modal = new ModalClient();
console.log("Authentication successful!");

package main

import (
    "fmt"
    "log"
    
    modal "github.com/modal-labs/modal-client/go"
)

func main() {
    // Credentials are automatically loaded from environment variables
    mc, err := modal.NewClient()
    if err != nil {
        log.Fatalf("Authentication failed: %v", err)
    }
    fmt.Println("Authentication successful!")
}

Programmatic authentication

You can also pass credentials directly when creating a client:

TypeScript
Go

import { ModalClient } from "modal";

const modal = new ModalClient({
  tokenId: "ak-YOUR_TOKEN_ID_HERE",
  tokenSecret: "as-YOUR_TOKEN_SECRET_HERE"
});

import modal "github.com/modal-labs/modal-client/go"

mc, err := modal.NewClient(
    modal.WithTokenID("ak-YOUR_TOKEN_ID_HERE"),
    modal.WithTokenSecret("as-YOUR_TOKEN_SECRET_HERE"),
)

Avoid hardcoding credentials in your source code. Use environment variables or a secrets manager instead.

Configuration file location

By default, the SDKs look for credentials in ~/.modal.toml. You can customize this location:

export MODAL_CONFIG_PATH=/path/to/custom/modal.toml

The configuration file format:

~/.modal.toml

[default]
token_id = "ak-YOUR_TOKEN_ID_HERE"
token_secret = "as-YOUR_TOKEN_SECRET_HERE"

Credential precedence

The SDKs check for credentials in this order:

Programmatic credentials passed to the client constructor
Environment variables (MODAL_TOKEN_ID and MODAL_TOKEN_SECRET)
Configuration file at ~/.modal.toml or $MODAL_CONFIG_PATH

Managing multiple accounts

If you need to work with multiple Modal accounts, you can:

Use different configuration file paths with MODAL_CONFIG_PATH
Create separate environment variable sets for each account
Pass different credentials programmatically to different client instances

Troubleshooting

Authentication errors

If you see authentication errors:

Check credentials

Verify that your MODAL_TOKEN_ID and MODAL_TOKEN_SECRET are set correctly:

echo $MODAL_TOKEN_ID
echo $MODAL_TOKEN_SECRET

Verify token is active

Check config file

If using a config file, verify it exists and has the correct format:

cat ~/.modal.toml

Re-run setup

If all else fails, re-run the setup process:

python3 -m modal setup

Permission errors

If you get permission errors when accessing resources:

Verify that your token has the necessary permissions
Check that you’re using the correct workspace/organization
Ensure the resources you’re trying to access exist and you have access to them

Security best practices

Never commit credentials

Add .modal.toml and credential files to .gitignore

Use environment variables

In production, use secrets managers or environment variables

Rotate tokens regularly

Generate new tokens periodically and revoke old ones

Use minimal permissions

Create tokens with only the permissions you need

Next steps

Now that you’re authenticated, you’re ready to start building:

Quick start guide

Build your first Modal application

Getting Started

Core Concepts

Python SDK

TypeScript SDK

Go SDK

Storage & Data

Configuration

Advanced

Migration & Changelog

Method 1: Interactive setup (recommended)

Method 2: Environment variables

Programmatic authentication

Configuration file location

Credential precedence

Managing multiple accounts

Troubleshooting

Authentication errors

Permission errors

Security best practices

Never commit credentials

Use environment variables

Rotate tokens regularly

Use minimal permissions

Next steps

Quick start guide

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Python SDK

TypeScript SDK

Go SDK

Storage & Data

Configuration

Advanced

Migration & Changelog

​Method 1: Interactive setup (recommended)

​Method 2: Environment variables

​Programmatic authentication

​Configuration file location

​Credential precedence

​Managing multiple accounts

​Troubleshooting

​Authentication errors

​Permission errors

​Security best practices

Never commit credentials

Use environment variables

Rotate tokens regularly

Use minimal permissions

​Next steps

Quick start guide

Build docs developers (and LLMs) love

Method 1: Interactive setup (recommended)

Method 2: Environment variables

Programmatic authentication

Configuration file location

Credential precedence

Managing multiple accounts

Troubleshooting

Authentication errors

Permission errors

Security best practices

Next steps