Authentication

define.wtf uses session-based authentication powered by Auth.js (next-auth v5). Your session is maintained via HTTP cookies, just like logging into the web application.

How It Works

1. You log in to define.wtf at https://{tenant-slug}.define.wtf
2. The server creates a session and sets a secure next-auth.session-token cookie
3. Your browser automatically includes this cookie on subsequent requests
4. The API validates the session and returns user-scoped data

Getting Your Session Token

For Browser-Based Code

If you're making requests from JavaScript in the browser, cookies are sent automatically. Just add credentials: 'include' to your fetch request:

fetch('https://engineering.define.wtf/api/v1/acronyms', {
  credentials: 'include', // Include cookies
})
  .then(res => res.json())
  .then(data => console.log(data))

For CLI Tools, Scripts, and Integrations

For server-to-server or script-based access, you must extract your session token from your browser:

Step 1: Log in to define.wtf

Navigate to your workspace: https://{tenant-slug}.define.wtf

Step 2: Copy your session token

Open your browser's DevTools (F12):

• Go to Application → Cookies → select your define.wtf domain
• Find the next-auth.session-token cookie
• Copy the full value

Step 3: Use it in your requests

With cURL:

curl -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" \
  https://engineering.define.wtf/api/v1/acronyms

With Node.js fetch:

const token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
const response = await fetch('https://engineering.define.wtf/api/v1/acronyms', {
  headers: {
    'Cookie': `next-auth.session-token=${token}`
  }
})
const data = await response.json()
console.log(data)

With Python requests:

import requests

token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
headers = {'Cookie': f'next-auth.session-token={token}'}
response = requests.get('https://engineering.define.wtf/api/v1/acronyms', headers=headers)
print(response.json())

Session Expiration

Sessions are valid for 30 days by default. When your session expires:

• All API requests return 401 Unauthorized
• You must log back into define.wtf to obtain a new session token
• The new next-auth.session-token cookie will be set automatically

Permissions and Roles

Your session includes your user role, which determines what API actions you can perform:

If you attempt an action without permission, the API returns 403 Forbidden:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to perform this action"
  }
}

Checking Your Authentication Status

You can test your authentication by attempting a simple read operation like listing acronyms:

curl -H "Cookie: next-auth.session-token=YOUR_SESSION_TOKEN" \
  https://engineering.define.wtf/api/v1/acronyms?limit=1

If you're authenticated, you'll receive a 200 OK with your workspace's acronyms. If not, you'll get:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Token Security

• Session tokens are httpOnly cookies — they cannot be accessed via JavaScript (except when making fetch requests)
• Do not share your token with untrusted applications or websites
• Rotate your token by logging out and logging back in at https://{tenant-slug}.define.wtf/logout
• Use HTTPS only — never send your token over unencrypted HTTP
• Limit token lifetime — 30-day expiration ensures stale tokens become invalid

Common Issues

401 Unauthorized on valid-looking requests:

• Verify the token hasn't expired (log in again)
• Check the cookie is being sent (use browser DevTools Network tab)
• Confirm you're using the correct tenant slug in the URL

403 Forbidden:

• Your user role doesn't have permission for this action
• Contact your workspace admin to request elevated permissions

Cookie not being sent:

• For browser requests, ensure credentials: 'include' is set
• For server requests, ensure the Cookie header is properly formatted
• Check that the domain in your request matches the domain where you logged in