Engramma

Authentication

beginner

Register, verify email, login, refresh tokens, logout, password reset, and MFA endpoints.

Registration

POST/v1/auth/register

Create a new user account. Returns tokens immediately; a verification email is sent in background.

emailstringrequired

Valid email address (format: email). Must be unique.

passwordstringrequired

Minimum 12 characters.

full_namestring | null

Display name for the account.

namestring | null

Alias for full_name.

organization_namestring | null

If provided, creates an organization during registration.

201Response
{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "[email protected]",
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "message": "Verification email sent"
}
curl -X POST https://api.engramma-memory.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SuperSecure123!",
    "full_name": "Alice",
    "organization_name": "Acme Corp"
  }'

Email verification

POST/v1/auth/verify-email

Verify a user's email address using the token sent during registration.

tokenstringrequired

The verification token from the email.

200Response
{
  "message": "Email verified successfully"
}

Resend verification

POST/v1/auth/resend-verification

Resend the verification email.

emailstringrequired

The email address to resend verification to.

200Response
{
  "message": "Verification email resent"
}

Login

POST/v1/auth/login

Authenticate and receive access + refresh tokens. If MFA is enabled, returns mfa_required: true instead of tokens.

emailstringrequired

Registered email address.

passwordstringrequired

Account password.

mfa_codestring | null

TOTP code (if MFA enabled and you want to complete login in one step).

recovery_codestring | null

Recovery code (alternative to mfa_code).

200Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 900,
  "mfa_required": false
}
Info

Access tokens expire in 15 minutes (900s). Use the refresh endpoint to get new tokens. If mfa_required is true, use the MFA login endpoint to complete authentication.

curl -X POST https://api.engramma-memory.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "SuperSecure123!"}'

Refresh token

POST/v1/auth/refresh

Exchange a refresh token for a new access + refresh token pair.

refresh_tokenstringrequired

The current refresh token.

200Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 900,
  "mfa_required": false
}

Logout

POST/v1/auth/logout

Invalidate the current session.

200Response
{
  "message": "Logged out successfully"
}

Logout all sessions

POST/v1/auth/logout-all

Invalidate all active sessions for the current user.

200Response
{
  "message": "All sessions revoked"
}

Forgot password

POST/v1/auth/forgot-password

Send a password reset link to the user's email.

emailstringrequired

The email address for the account.

200Response
{
  "message": "If an account exists with this email, a reset link has been sent"
}
Info

Always returns 200 to prevent email enumeration.

Reset password

POST/v1/auth/reset-password

Set a new password using the reset token from the email.

tokenstringrequired

The reset token from the email link.

new_passwordstringrequired

New password (minimum 12 characters).

200Response
{
  "message": "Password reset successfully"
}

MFA: Enable

POST/v1/auth/mfa/enable

Start the MFA enrollment process.

200Response
{
  "message": "MFA enrollment started"
}

MFA: Setup

POST/v1/auth/mfa/setup

Get the TOTP secret and otpauth URI for QR code display.

200Response
{
  "secret": "JBSWY3DPEHPK3PXP",
  "otpauth_uri": "otpauth://totp/Engramma:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=Engramma",
  "message": "Scan the QR code, then verify with a code to enable MFA"
}

MFA: Verify

POST/v1/auth/mfa/verify

Confirm MFA setup by providing the first TOTP code. Returns recovery codes.

codestringrequired

A 6-digit TOTP code from the authenticator app.

200Response
{
  "message": "MFA enabled successfully",
  "recovery_codes": [
    "a1b2c3d4e5f6",
    "g7h8i9j0k1l2",
    "m3n4o5p6q7r8",
    "s9t0u1v2w3x4",
    "y5z6a7b8c9d0"
  ]
}
Danger

Store recovery codes securely. They cannot be retrieved after this response. Each code can only be used once.

MFA: Login

POST/v1/auth/mfa/login

Complete login when MFA is required. Called after login returns mfa_required: true.

codestringrequired

6-digit TOTP code or a recovery code.

tokenstring | null

Temporary MFA token (if provided by the login response).

200Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 900
}

MFA: Disable

POST/v1/auth/mfa/disable

Disable MFA on the account. Requires a valid TOTP code.

codestringrequired

A valid 6-digit TOTP code to confirm identity.

200Response
{
  "message": "MFA disabled successfully"
}

JWKS (JSON Web Key Set)

GET/.well-known/jwks.json

Public keys for JWT signature verification. Use this to validate tokens client-side.

200Response
{
  "keys": [
    {
      "kty": "RSA",
      "kid": "...",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

User profile

User profile management has moved to dedicated endpoints:

  • GET /v1/users/me — Get current user profile
  • PATCH /v1/users/me — Update profile
  • DELETE /v1/users/me — Delete account
  • PUT /v1/users/me/password — Change password

See Users for details.

Next steps

  • Memory Core — Store and retrieve memories
  • Security — Session management and audit logs
  • Errors — Authentication error codes
OverviewHealth