truthseek
For Developers

Authentication

The truthseek API uses JWT (JSON Web Tokens) for authentication. This guide covers how to obtain tokens, authenticate requests, and manage sessions securely.

Authentication Flow

1
Login
Send credentials
2
Receive
Get tokens
3
Use
Include in requests
4
Refresh
When token expires

Obtaining Tokens

Password Authentication

POST/auth/login
Authenticate with email and password.
{
  "email": "user@example.com",
  "password": "your_password"
}

Successful response:

login_response.jsonjson
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
  "token_type": "bearer",
  "expires_in": 3600
}

OAuth Authentication

truthseek supports OAuth 2.0 with the following providers:

🔵Google
⚫GitHub
🐦Twitter/X
GET/auth/oauth/{provider}
Initiate OAuth flow. Redirects to provider's authorization page.

Using Access Tokens

Include the access token in the Authorization header:

GET /api/v1/claims HTTP/1.1
Host: api.truthseek.io
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Access Token
Expires after 1 hour
Used for API requests
Refresh Token
Expires after 30 days
Used to get new access tokens

Refreshing Tokens

When an access token expires, use the refresh token to get a new one:

POST/auth/refresh
Exchange refresh token for new access token.
{
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl..."
}

Token Rotation

Each refresh invalidates the old refresh token and returns a new one. This limits the window of opportunity if a token is compromised.

Registration

POST/auth/register
Create a new account.
{
  "email": "newuser@example.com",
  "password": "secure_password",
  "username": "newuser",
  "display_name": "New User"
}

Requirements

Password

  • • Minimum 8 characters
  • • At least one uppercase letter
  • • At least one lowercase letter
  • • At least one number

Username

  • • 3-30 characters
  • • Alphanumeric and underscores only
  • • Must be unique
  • • Cannot be changed later

Security Best Practices

Token Storage

EnvironmentRecommended Storage
Browser (SPA)HttpOnly cookies or memory only
Mobile AppSecure keychain/keystore
Server-sideEnvironment variables or secrets manager

Security Warnings

  • • Never store tokens in localStorage (XSS vulnerable)
  • • Never include tokens in URLs
  • • Never log tokens in application logs
  • • Never share tokens between users

Error Responses

401 Unauthorized

{
  "detail": "Invalid or expired token"
}

Common causes:

  • Missing Authorization header
  • Malformed token
  • Expired access token
  • Revoked token

403 Forbidden

{
  "detail": "Insufficient permissions"
}

The token is valid, but the user doesn't have permission for the requested action.