Account and authentication

You need an account before you can run anything. There is no free-standing API key to manage: the CLI holds a session for you, the dashboard signs you in with the same credentials, and the REST API authenticates with the same email and password.

Create an account from the CLI

This is the fastest way, and it leaves you signed in.

distil signup

The command needs the CLI. If you do not have it yet, install it first: Ways to use distil labs.

distil signup opens the sign-up page in your browser, then waits. Three steps finish the job:

1. Fill in the form and submit it.
2. Open the confirmation email and confirm your address.
3. Return to the page and sign in with the same email and password.

Step 3 is the one that surprises people. Submitting the form creates the account, but it does not sign you in. The sign-in after the confirmation is what returns the session to the CLI. The command then prints Logged in as <email> and you are signed in, with no further login step.

Sign in within 20 minutes, while the hand-off is still valid. Any tab in the same browser works, because the CLI hand-off travels in a cookie rather than in the page URL.

Create an account from the browser

Sign up at app.distillabs.ai/sign-up. Confirm your email address, then sign in.

This creates the same account. It gives the CLI no session, so bring the account to your terminal with distil auth before you run anything. The next section covers that command.

Sign in to the CLI

distil auth

This opens the sign-in page and hands the session back when you are done.

On a machine with no browser, CI for example, pass the credentials directly:

distil auth --email you@example.com --password "$DISTIL_PASSWORD"

Check who you are signed in as, or sign out:

distil whoami
distil logout

The CLI keeps its own session, in ~/.config/distillabs/token (under $XDG_CONFIG_HOME when that is set), and refreshes it for you. A run spanning several hours will not ask you to log in again.

Sign in to the dashboard

Go to app.distillabs.ai and sign in with the same email and password. The two sessions are separate: signing in here does not sign in the CLI, and distil auth does not sign in the browser.

The dashboard is read-only. It lists your models, datasets and traces, and you start every job from the CLI or the REST API. See Ways to use distil labs.

To reset a forgotten password, select Forgot password? on the sign-in page. The CLI has no reset command, so this is the only way to do it.

Authenticate with the REST API

The REST API takes an access token from Cognito, minted with the same email and password. Tokens last one hour, which is shorter than a training run, so fetch one per request rather than holding it:

response = requests.get(
    "https://api.distillabs.ai/seed-datasets",
    headers={"Authorization": access_token},
)

Using the REST API has the auth() helper that mints the token, along with the rest of the helpers the API examples depend on. Do not copy the auth block on its own. The surrounding helpers handle the error bodies where validation failures actually live.

Troubleshooting

Not logged in or session expired. Run `distil auth` to authenticate or `distil signup` to create an account.

Run distil auth. If you have no account yet, distil signup first.

Invalid email or password.

Wrong credentials on distil auth --email … --password ….

Email confirmation required. Please check your email and confirm your account.

The account exists but is not confirmed yet. Open the confirmation email, then authenticate again.

Timed out waiting for browser authorization

The browser flow did not finish. Authenticate headlessly instead, with --email and --password.

A 401 from the API means the credentials are wrong. A 403 usually means the token has expired, so mint a new one. More symptoms and their fixes: Troubleshooting.

Next

You have an account. Now build a model, or pick your task type first with Task selection.