Authentication

Queria supports several authentication methods to cover every integration scenario, from interactive web apps to server-to-server integrations.

Authentication methods

Method	Main use	Header
JWT Token	User sessions (dashboard, web apps)	Authorization: Bearer {token}
API Key	Integrations and widgets	X-API-Key: {key}

JWT (JSON Web Token)

The JWT method is suited for web applications with user sessions.

Login

curl -X POST https://api.queria.pro/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@company.com",
    "password": "secure_password"
  }'

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "rt_9f8e7d6c5b4a3210...",
    "expiresIn": 3600,
    "user": {
      "id": "usr_a1b2c3",
      "email": "user@company.com",
      "name": "Mario Rossi",
      "role": "COMPANY_ADMIN",
      "companyId": "comp_x1y2z3"
    }
  }
}

The access token is valid for 1 hour. Include it in every request:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Token structure

The JWT contains the following information:

{
  "sub": "usr_a1b2c3",
  "email": "user@company.com",
  "role": "COMPANY_ADMIN",
  "companyId": "comp_x1y2z3",
  "iat": 1709542800,
  "exp": 1709546400
}

Token refresh

Before expiration, renew the token with the refresh token:

curl -X POST https://api.queria.pro/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "rt_9f8e7d6c5b4a3210..."
  }'

Response:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "rt_a1b2c3d4e5f60000...",
    "expiresIn": 3600
  }
}

Logout

curl -X POST https://api.queria.pro/api/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Session check

curl -X GET https://api.queria.pro/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

API Key

API Keys are the recommended method for server-to-server integrations and widgets.

Format

Environment	Prefix	Example
Production	qk_live_	qk_live_abc123def456ghi789jkl012
Test	qk_test_	qk_test_mno345pqr678stu901vwx234

Usage

Include the key in the X-API-Key header:

curl -X POST https://api.queria.pro/api/public/chat \
  -H "X-API-Key: qk_live_abc123def456ghi789jkl012" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is the vacation policy?"}'

Generation

API Keys are generated from the admin dashboard:

1. Sign in to Settings in the admin panel
2. Select API Keys
3. Click Generate New Key
4. Copy immediately the key (shown only once)
5. Configure restrictions (optional)

Authorized domains

For security, configure the domains from which the API Key can be used:

# Dashboard > Settings > API Keys > Edit

Authorized domains:
- example.com
- *.example.com
- app.mysite.com

Requests from non-authorized domains will receive a 403 error.

Notice

Key deletion is immediate and irreversible. Make sure no integration is using it before proceeding.

OAuth (Social Login)

Queria supports authentication via OAuth providers.

Google

curl -X POST https://api.queria.pro/api/auth/google \
  -H "Content-Type: application/json" \
  -d '{"idToken": "google_id_token_here"}'

Microsoft

curl -X POST https://api.queria.pro/api/auth/microsoft \
  -H "Content-Type: application/json" \
  -d '{"accessToken": "microsoft_access_token_here"}'

Both return the same response format as standard login with accessToken and refreshToken.

Roles and permissions (RBAC)

The system uses a hierarchical RBAC model for access control.

Role	Scope	Description
COMPANY_ADMIN	Company	User, document and company settings management
COMPANY_EDITOR	Company	Upload, edit and delete documents, use chat
COMPANY_READER	Company	Read-only documents and chat use

Permission matrix

Action	COMPANY_ADMIN	COMPANY_EDITOR	COMPANY_READER
Cog-RAG configuration	Yes	No	No
User management	Yes	No	No
Document upload	Yes	Yes	No
Delete documents	Yes	Yes	No
AI chat	Yes	Yes	Yes
View documents	Yes	Yes	Yes

Authorization errors

401 Unauthorized - Missing or expired token:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Token missing or invalid"
  }
}

403 Forbidden - Insufficient permissions:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions. Required role: COMPANY_ADMIN.",
    "requiredRole": "COMPANY_ADMIN",
    "currentRole": "COMPANY_READER"
  }
}

403 Forbidden - Unauthorized domain (API Key):

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Unauthorized domain for this API Key"
  }
}

Security best practices

Token management

• Don't store tokens in localStorage (vulnerable to XSS)
• Use httpOnly cookies when possible
• Implement automatic refresh before token expiration

API Keys

• Don't include API Keys in client-side code
• Use environment variables to store keys on servers
• Rotate keys regularly (at least every 90 days)
• Limit authorized domains for each key

Method choice

Scenario	Recommended method
Web app with user login	JWT
Widget embedded on third-party sites	API Key with domain restriction
Server-to-server integration	API Key
Mobile app	JWT with refresh token
Automation script	API Key with expiration

Fundamental rules

• Always use HTTPS for all communications
• Implement rate limiting client-side to avoid blocks
• Monitor key usage from the dashboard
• Revoke immediately compromised keys