Skip to content

Password Authentication¶

PhyWare supports email/password authentication for user accounts scoped to a tenant. This is the non-SSO complement to device-code login; both issue equivalent session tokens.

Quick Start¶

# Invite a user (admin)
phyware users invite --email alice@example.com --tenant acme

# User accepts the invite and sets a password
curl -X POST https://cloud.phyware.io/api/v1/users/accept-invite \
  -H "Content-Type: application/json" \
  -d '{"token": "<invite-token>", "password": "StrongP@ssword12"}'

# Login
phyware auth login --email alice@example.com --tenant acme

Password Policy¶

Requirement	Value
Minimum length	12 characters
Algorithm	Argon2id
Common-password block	Yes (built-in list, no external calls)
Breach check	Built-in hash-set

Argon2id Parameters¶

Default parameters are tuned for a web service. They can be overridden via environment variables for CI performance:

Variable	Default	Description
`PHYWARE_ARGON2_TIME_COST`	`3`	Iterations
`PHYWARE_ARGON2_MEMORY_COST`	`65536`	KiB (64 MiB)
`PHYWARE_ARGON2_PARALLELISM`	`4`	Parallel lanes
`PHYWARE_ARGON2_HASH_LEN`	`32`	Output bytes
`PHYWARE_ARGON2_SALT_LEN`	`16`	Salt bytes

API Endpoints¶

POST /api/v1/auth/password/login
Header: X-Tenant-ID: <tenant-id>
Body:   { "email": "...", "password": "..." }

Returns a session_id (raw token, shown once) that can be used as a Bearer token.

Change Password¶

POST /api/v1/auth/password/change
Header: X-Tenant-ID: <tenant-id>
Header: X-User-ID: <user-id>
Body:   { "current_password": "...", "new_password": "..." }

Reset Password¶

Initiate reset (always returns 204 to prevent user enumeration):

POST /api/v1/auth/password/reset-request
Header: X-Tenant-ID: <tenant-id>
Body:   { "email": "..." }

Confirm reset with single-use token (TTL ≤ 1 hour):

POST /api/v1/auth/password/reset-confirm
Body:   { "token": "...", "new_password": "..." }

Session Management¶

# List sessions
GET /api/v1/auth/sessions
Header: X-User-ID: <user-id>

# Revoke session
POST /api/v1/auth/sessions/logout
Header: X-Session-ID: <raw-session-id>

CLI¶

# Login interactively (prompts for password)
phyware auth login --email alice@example.com --tenant acme

# List sessions
phyware auth sessions list --user-id usr_abc123

# Revoke a session
phyware auth sessions revoke <session-id>

Security Notes¶

All login and reset-request endpoints return identical responses for unknown/known emails to prevent user enumeration.
Password reset tokens are single-use with a TTL of ≤ 1 hour.
Session tokens are stored as SHA-256 hashes; the raw token is returned once at login time and never persisted.
All new endpoints are rate-limited per source IP.