Authentication

GenLabZ uses a central identity service for platform access. Authentication identifies you as an author, coordinator, student, or admin — it’s separate from the AWS sandbox accounts used for project work. You authenticate once, and the CLI handles token management from there.

Signing in

Run genlabz auth login to start a browser-based sign-in flow:

Terminal

genlabz auth login

When you run this command:

1. Your default browser opens to the GenLabZ sign-in page (hosted by Amazon Cognito)
2. You sign in with your email and password
3. The browser redirects back to a local callback on your machine
4. Tokens are stored at ~/.genlabz/credentials.json

Once complete, the CLI prints a confirmation with your token expiry time:

Logged in successfully. Token expires at 2026-04-23T15:30:00Z

You’re now authenticated and can use commands that require platform identity.

Note

If the browser doesn’t open automatically, copy the URL from the terminal output and paste it into your browser manually.

Checking your status

Run genlabz auth status to see who you’re logged in as:

Terminal

genlabz auth status

This displays your email address, group memberships (e.g. authors, admins), and when your current token expires:

Email:   you@example.com
Groups:  authors
Expires: 2026-04-23T15:30:00Z

If you’re not logged in, the command prints:

Not logged in.

Signing out

Run genlabz auth logout to clear your stored tokens:

Terminal

genlabz auth logout

This revokes your refresh token server-side and deletes the local credential file. You’ll need to run genlabz auth login again to re-authenticate.

Logged out. Tokens cleared.

Tip

If you’re on a shared machine, always sign out when you’re done to prevent others from using your session.

Token management

Tokens are stored locally at ~/.genlabz/credentials.json with file permissions restricted to your user account (owner read/write only).

Two token types are in play:

• Access token — valid for 1 hour, used to authenticate API requests
• Refresh token — valid for 30 days, used to obtain new access tokens without re-signing in

When your access token is within 5 minutes of expiry, the CLI and SDK automatically refresh it using the refresh token. You don’t need to do anything — sessions stay active as long as the refresh token is valid.

If the refresh token itself expires (after 30 days of inactivity), you’ll need to run genlabz auth login again.