Account

These endpoints handle the full account lifecycle: creating and authenticating accounts, verifying email addresses, recovering passwords, managing profile and security settings, and setting up two-factor authentication.

The lifecycle endpoints (/v1/login, /v1/register, /v1/reset-password, /v1/verify-email, /v1/lock-account) do not require a bearer token. They are open to any caller but carry tighter rate limits than the rest of the API.

---

Authentication + lifecycle

Log in

POST/v1/loginAuthenticate and mint a SESSION token

Validates the email and password (and a TOTP code if 2FA is enabled), sends a login notification email, and returns a SESSION-origin token with the full USER-scope permission map. The plaintext code is only returned once; save it securely.

No authentication required.

Request body

Field	Type	Required	Description
email	string	yes	Account email address
password	string	yes	Account password
mfa	string		TOTP code (required when 2FA is enabled on the account; pass the emergency reset token here to disable 2FA)

curl -X POST https://api.galaxygate.net/v1/login \
  -A 'curl/8.5' \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "password": "hunter2", "mfa": "123456" }'

Returns a token object. The code field is the bearer token to use in subsequent requests; it is the only time the plaintext is exposed.

---

Register

POST/v1/registerCreate a new account

Creates a new user account and starts the onboarding workflow (email verification email, default workspace, optional coupon redemption). If a user with the same email already exists, the server sends a password-reset email to that address and returns 201 without revealing that the account exists.

No authentication required.

Request body

Field	Type	Required	Description
name	string	yes	Display name (3-32 characters)
email	string	yes	Email address
password	string	yes	Password (minimum 8 characters)
coupon	string		Promotional coupon code
invite_code	string		Workspace invite code; accepting an invite addressed to this email also verifies it

Returns 201 Created with an empty body.

---

Request or confirm a password reset

POST/v1/reset-passwordRequest or confirm a password reset

This endpoint handles both steps of the reset flow in a single path. Send exactly one of email or code.

No authentication required.

Request body (step 1 - request a reset link)

Field	Type	Required	Description
email	string	yes (this step)	Email address to send the reset link to

Request body (step 2 - set the new password)

Field	Type	Required	Description
code	string	yes (this step)	Token from the reset link
password	string	yes (this step)	New password (minimum 8 characters)

Returns 202 Accepted with an empty body for both steps.

---

Request or confirm email verification

POST/v1/verify-emailRequest or confirm email verification

Handles both steps of the email verification flow. Send exactly one of email or code.

No authentication required.

Request body (step 1 - resend the verification email)

Field	Type	Required	Description
email	string	yes (this step)	Account email address

Request body (step 2 - confirm the code)

Field	Type	Required	Description
code	string	yes (this step)	Token from the verification email

Returns 202 Accepted with an empty body.

---

Lock an account

POST/v1/lock-accountLock an account using its lock code

Immediately locks the account identified by its lock code. Lock codes are included in login-notification emails as a one-click security action. A locked account cannot log in. Idempotent: locking an already-locked account returns 202 without error.

No authentication required.

Request body

Field	Type	Required	Description
code	string	yes	Account lock code (from the login notification email)

Returns 202 Accepted with an empty body.

---

Profile + security

Fetch a user profile

GET/v1/users/{id}Fetch user profile

Path parameters

Name	Type	Description
id	string	User ID, or @me for the authenticated user

curl https://api.galaxygate.net/v1/users/@me \
  -A 'curl/8.5' \
  -H "Authorization: Bearer $GALAXYGATE_TOKEN"

Returns the user object.

---

Update a user profile

PATCH/v1/users/{id}Update account profile

Updates the user's display name or email address. All fields are optional; send only what you are changing. An email change triggers a confirmation link to the new address before it takes effect.

Path parameters

Name	Type	Description
id	string	User ID, or @me

Request body

Field	Type	Description
name	string	Display name (3-32 characters)
email	string	New email address; a confirmation link is sent before the change is applied

Returns the updated user object.

---

Delete an account

DELETE/v1/users/{id}Permanently deactivate an account

Permanently deactivates the account and revokes all active sessions. The account must not own any workspaces; transfer or delete them first.

Path parameters

Name	Type	Description
id	string	User ID, or @me

Returns 202 Accepted with an empty body.

---

Change password

PUT/v1/users/{id}/passwordChange account password

Updates the account password. Invalidates all active sessions, including the one used to make this call.

Path parameters

Name	Type	Description
id	string	User ID, or @me

Request body

Field	Type	Required	Description
old_password	string	yes	Current password
password	string	yes	New password (minimum 8 characters)

Returns 202 Accepted with an empty body.

---

Begin 2FA setup

POST/v1/users/{uid}/totpBegin two-factor authentication setup

Generates a TOTP secret and returns the provisioning URI, the raw secret, and an emergency reset token. Call PUT /v1/users/{uid}/totp with a valid code to confirm and activate 2FA.

Path parameters

Name	Type	Description
uid	string	User ID, or @me

Returns

Field	Type	Description
uri	string	otpauth:// URI ready to scan with an authenticator app
code	string	Raw TOTP secret
reset	string	Emergency reset token; store it somewhere safe. Pass it as mfa at login to disable 2FA.

---

Finalize 2FA setup

PUT/v1/users/{uid}/totpConfirm and activate two-factor authentication

Confirms a TOTP code generated by the authenticator app and activates 2FA. All active sessions are invalidated.

Path parameters

Name	Type	Description
uid	string	User ID, or @me

Request body

Field	Type	Required	Description
code	string	yes	Current TOTP code from the authenticator app

Returns 202 Accepted with an empty body.

---

Disable 2FA

DELETE/v1/users/{uid}/totpDisable two-factor authentication

Removes the TOTP secret and disables 2FA on the account. Requires the current TOTP code passed in the X-MFA header.

Path parameters

Name	Type	Description
uid	string	User ID, or @me

Headers

Name	Required	Description
X-MFA	yes	Current TOTP code

Returns 202 Accepted with an empty body.

---

List invites addressed to a user

GET/v1/users/{uid}/invitesList invites addressed to the user

Returns workspace invites that were sent to this user's email address. Supports pagination.

Path parameters

Name	Type	Description
uid	string	User ID, or @me

Returns a paged list of invite objects.