Authentication

The CLI supports two authentication methods. Most operations require both.

API Key Authentication

Get an API key from preprod.app.andamio.io/api-setup, then store it:

andamio auth login --api-key YOUR_API_KEY

Check status:

andamio auth status

User Authentication (Wallet Login)

Write operations (import, export) require wallet-based authentication. This proves you own an Access Token and have teacher permissions on the course.

andamio user login

This opens your browser to sign a message with your Cardano wallet. After signing, a JWT is stored locally and included in subsequent requests.

Check your session:

andamio user status

Authentication Status
---------------------
API Key: ****... (configured)
Base URL: https://preprod.api.andamio.io

User: your-alias
Session: active (expires in 23h 45m)

Headless Login (CI/CD & Scripting)

For automated workflows — CI/CD pipelines, agents, multi-wallet testing — authenticate with a .skey file instead of a browser:

andamio user login --skey ./payment.skey --alias myalias

This signs a nonce with your Cardano signing key using CIP-8 message signing. No browser, no TTY required.

The flow:

1. CLI requests a login session (nonce) from the API
2. Signs the nonce locally with your .skey using CIP-8 message signing (private key never leaves your machine)
3. Sends signature to the API for verification
4. API returns a JWT; CLI stores it in config for subsequent commands

CI/CD Example

# Authenticate and capture the result
andamio user login --skey ./payment.skey --alias dev1 --output json
# Returns: {"alias":"dev1","user_id":"...","key_hash":"..."}

# Now use authenticated commands
andamio project owner list
andamio course owner list

Unlike browser login, --skey always re-authenticates (no "already logged in" check), making it safe for scheduled scripts.

Requirements

• An API key must be configured first (andamio auth login --api-key)
• A Cardano .skey file (payment signing key from cardano-cli)
• The --alias flag is required — this is the Andamio username you registered with andamio user login

End-to-End Example: Headless Login + Transaction

Combine headless login with tx run for fully automated on-chain operations:

# 1. Authenticate with signing key
andamio user login --skey ./payment.skey --alias badger

# 2. Run a transaction using tx run (follows the tx state machine)
andamio tx run /v2/tx/course/student/assignment/commit \
  --body '{"alias":"badger","course_id":"76bab0...","slt_hash":"77547a...","assignment_info":"...","initiator_data":{"change_address":"addr_test1...","used_addresses":["addr_test1..."]}}' \
  --skey ./payment.skey \
  --tx-type assignment_submit \
  --instance-id 76bab0...

# 3. Submit evidence off-chain (separate step)
andamio course student submit --course-id 76bab0... --module-code 101 \
  --evidence-file ./my-evidence.md

All transactions follow the same pattern: build → sign → submit → register → gateway confirms. tx run composes these steps. Off-chain operations (evidence submission) are separate commands.

No browser, no wallet extension, no interactive prompts. This flow works in CI/CD pipelines, cron jobs, and agent harnesses.

Session Management

JWTs expire after 24 hours. When your session expires:

andamio user logout
andamio user login

Check If a User Exists

Look up any user by alias:

andamio user exists <alias>

Returns { "alias": "...", "exists": true } — useful for scripting and verifying aliases before creating tasks or courses.

Check Your Roles

After logging in, verify what you have access to:

# Full dashboard — courses, projects, credentials
andamio user me

# Courses where you're a teacher (can import/export content, review submissions)
andamio teacher courses

# Projects where you're a manager (can create/manage tasks, review commitments)
andamio manager projects

# Courses you own
andamio course owner list

# Courses you're enrolled in as a student
andamio course student courses

# Projects you own
andamio project owner list

# Projects you contribute to
andamio project contributor list

Troubleshooting

unauthorized errors — Run andamio user status to check if your JWT has expired. If so, log out and log back in.

forbidden errors — You may not have the required role. Check which roles you have:

• andamio teacher courses — teacher access
• andamio manager projects — manager access
• andamio course student courses — student enrollment
• andamio project contributor list — contributor access

Browser doesn't open — The CLI starts a local server and opens your default browser. If it doesn't open automatically, copy the URL from the terminal output.