Authentication

How to authenticate with Atract's API.

Overview

Atract uses session-based authentication with wallet signatures.

Login Flow

1. User connects wallet (MetaMask/WalletConnect)

2. Frontend requests challenge message

3. User signs message with wallet

4. Backend verifies signature

5. Session created, cookie returned

Request Challenge

POST /api/auth/challenge
Content-Type: application/json

{
  "address": "0x..."
}

Response:

{
  "ok": true,
  "data": {
    "message": "Sign this message to authenticate with Atract...",
    "nonce": "abc123"
  }
}

Submit Signature

POST /api/auth/login
Content-Type: application/json

{
  "address": "0x...",
  "signature": "0x...",
  "nonce": "abc123"
}

Response:

{
  "ok": true,
  "data": {
    "user": {
      "address": "0x...",
      "sessionToken": "..."
    }
  }
}

Sets Cookie:

Set-Cookie: session=<token>; HttpOnly; Secure; SameSite=Strict

Authenticated Requests

Include session cookie in all requests:

GET /api/account
Cookie: session=<token>

Logout

POST /api/auth/logout
Cookie: session=<token>

Session Expiry

• Sessions expire after 24 hours

• Refresh by making any authenticated request

• After expiry, user must re-authenticate

Security

• Signatures verified on backend

• Session tokens are random, secure

• HttpOnly cookies prevent XSS

• HTTPS required in production

Related Pages

• API Reference

• Local Development