Authentication

Legistry AI uses JWT (JSON Web Tokens) for authentication. All API requests must include a valid token in the Authorization header.

Authentication Methods

Method	Use Case	How to Get
JWT Token	User-scoped requests (dashboard, UI)	Login via `/auth/login`
API Key	Server-to-server integration	Generate in Dashboard → Settings

JWT Authentication

Login

POST https://api.legistry.ai/api/v1/auth/login

{
  "email": "user@company.com",
  "password": "your-password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_expires_in": 604800,
  "user": {
    "id": "uuid-...",
    "email": "user@company.com",
    "full_name": "John Doe",
    "organization_id": "org-uuid-...",
    "role": "owner"
  }
}

Using the Token

Include the access token in all subsequent requests:

curl -X GET https://api.legistry.ai/api/v1/contracts \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token Refresh

Access tokens expire after 30 minutes. Use the refresh token to get a new one:

POST https://api.legistry.ai/api/v1/auth/refresh

{
  "refresh_token": "eyJhbGciOiJIUzI1NiIs..."
}

Refresh tokens are valid for 7 days. After expiry, the user must log in again.

Logout

Revoke the current token:

POST https://api.legistry.ai/api/v1/auth/logout

Authorization: Bearer YOUR_ACCESS_TOKEN

The token will be blacklisted and can no longer be used.

MFA (Multi-Factor Authentication)

If your organization has MFA enabled, the login flow includes an additional step:

Login → Returns mfa_required: true + mfa_token
Verify MFA → Submit TOTP code with the mfa_token
Receive → Full access token + refresh token

POST https://api.legistry.ai/api/v1/auth/mfa/verify

{
  "mfa_token": "temp-token-from-login",
  "code": "123456"
}

Rate Limits

Endpoint	Limit
`POST /auth/login`	5 requests / minute
`POST /auth/register`	3 requests / minute
`POST /auth/password/reset-request`	3 requests / 5 minutes
All other endpoints	60 requests / minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709913600

Roles & Permissions

Legistry AI uses role-based access control (RBAC):

Role	Contracts	Signatures	Team	Billing	Settings
Owner	Full	Full	Full	Full	Full
Admin	Full	Full	Full	View	Full
Member	Create/Edit	Send/Sign	View	—	Own Profile
Viewer	View Only	View Only	View	—	Own Profile

Error Responses

Authentication errors return standard HTTP status codes:

Code	Meaning
`401 Unauthorized`	Missing or invalid token
`403 Forbidden`	Valid token, insufficient permissions
`429 Too Many Requests`	Rate limit exceeded

Getting Started Overview