Engramma

Authentication

beginner

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

Registration

POST/v1/auth/register

Create a new user account. Returns a verification token sent to the provided email.

emailstringrequired

Valid email address. Must be unique across the platform.

passwordstringrequired

Minimum 8 characters, must include uppercase, lowercase, and a number.

namestringrequired

Display name for the account.

201Response
{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "Alice",
  "verified": false,
  "created_at": "2026-01-15T10:00:00Z",
  "message": "Verification email sent"
}
from engramma_cloud import EngrammaClient

client = EngrammaClient()
user = client.auth.register(
    email="[email protected]",
    password="SecurePass123",
    name="Alice"
)
print(user.id)  # "usr_abc123"

Email verification

POST/v1/auth/verify

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

tokenstringrequired

The 6-digit verification code from the email.

emailstringrequired

The email address to verify.

200Response
{
  "verified": true,
  "message": "Email verified successfully"
}
result = client.auth.verify(
    email="[email protected]",
    token="482910"
)
print(result.verified)  # True

Resend verification

POST/v1/auth/verify/resend

Resend the verification email. Rate-limited to 1 per minute.

emailstringrequired

The email address to resend verification to.

200Response
{
  "message": "Verification email resent",
  "expires_in": 600
}

Login

POST/v1/auth/login

Authenticate and receive access + refresh tokens. If MFA is enabled, returns a challenge instead.

emailstringrequired

Registered email address.

passwordstringrequired

Account password.

200Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "rt_abc123def456...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user": {
    "id": "usr_abc123",
    "email": "[email protected]",
    "name": "Alice",
    "mfa_enabled": false
  }
}
tokens = client.auth.login(
    email="[email protected]",
    password="SecurePass123"
)
print(tokens.access_token)
print(f"Expires in {tokens.expires_in}s")
Info

If MFA is enabled, login returns {"mfa_required": true, "mfa_token": "..."} instead. Use the MFA verify endpoint to complete authentication.

Refresh token

POST/v1/auth/refresh

Exchange a refresh token for a new access token. The refresh token is rotated.

refresh_tokenstringrequired

The current refresh token (starts with rt_).

200Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "rt_new789ghi012...",
  "token_type": "Bearer",
  "expires_in": 3600
}
new_tokens = client.auth.refresh(
    refresh_token="rt_abc123def456..."
)
# SDK handles this automatically when access_token expires

Logout

POST/v1/auth/logout

Invalidate the current session. Both access and refresh tokens are revoked.

200Response
{
  "message": "Logged out successfully"
}
client.auth.logout()

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",
  "expires_in": 3600
}
Info

This endpoint always returns 200, even if the email doesn't exist. This prevents email enumeration attacks.

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.

passwordstringrequired

New password. Same requirements as registration.

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

Change password

POST/v1/auth/change-password

Change password while authenticated. Requires the current password for verification.

current_passwordstringrequired

The current account password.

new_passwordstringrequired

The new password.

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

MFA: Enable

POST/v1/auth/mfa/enable

Start the MFA enrollment process. Returns a TOTP secret and QR code URL.

200Response
{
  "secret": "JBSWY3DPEHPK3PXP",
  "qr_code_url": "otpauth://totp/Engramma:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=Engramma",
  "backup_codes": [
    "a1b2c3d4",
    "e5f6g7h8",
    "i9j0k1l2",
    "m3n4o5p6",
    "q7r8s9t0"
  ]
}
mfa = client.auth.mfa.enable()
print(f"Secret: {mfa.secret}")
print(f"QR: {mfa.qr_code_url}")
print(f"Backup codes: {mfa.backup_codes}")
# User scans QR code with authenticator app
Danger

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

MFA: Setup confirm

POST/v1/auth/mfa/setup

Confirm MFA setup by providing the first TOTP code. MFA is not active until this step succeeds.

codestringrequired

A 6-digit TOTP code from the authenticator app.

200Response
{
  "mfa_enabled": true,
  "message": "MFA enabled successfully"
}

MFA: Verify (during login)

POST/v1/auth/mfa/verify

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

mfa_tokenstringrequired

The temporary MFA token from the login response.

codestringrequired

6-digit TOTP code or a backup code.

200Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "rt_abc123def456...",
  "token_type": "Bearer",
  "expires_in": 3600
}
# Step 1: Login returns MFA challenge
challenge = client.auth.login(
    email="[email protected]",
    password="SecurePass123"
)
# challenge.mfa_required == True

# Step 2: Complete with TOTP code
tokens = client.auth.mfa.verify(
    mfa_token=challenge.mfa_token,
    code="482910"
)
print(tokens.access_token)

MFA: Disable

POST/v1/auth/mfa/disable

Disable MFA on the account. Requires a valid TOTP code or backup code for security.

codestringrequired

A valid 6-digit TOTP code or backup code to confirm identity.

200Response
{
  "mfa_enabled": false,
  "message": "MFA disabled successfully"
}

Get current user

GET/v1/auth/me

Retrieve the authenticated user's profile information.

200Response
{
  "id": "usr_abc123",
  "email": "[email protected]",
  "name": "Alice",
  "verified": true,
  "mfa_enabled": true,
  "created_at": "2026-01-15T10:00:00Z",
  "last_login_at": "2026-01-20T14:30:00Z",
  "organizations": [
    {
      "id": "org_xyz789",
      "name": "Acme Engineering",
      "role": "admin"
    }
  ]
}
me = client.auth.me()
print(f"{me.name} ({me.email})")
print(f"MFA: {'enabled' if me.mfa_enabled else 'disabled'}")
for org in me.organizations:
    print(f"  {org.name} — {org.role}")

Next steps

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