Authentication

Assimetria OS supports three authentication methods: JWT Bearer tokens, httpOnly cookies, and organization API keys.

JWT Bearer tokens

The primary authentication method. Obtain a token by logging in, then include it in the Authorization header.

Login

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

Response:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "refresh_token": "a1b2c3d4e5...",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "role": "admin"
  }
}

Using the token

Include the JWT in the Authorization header on every request:

curl https://api.orkosi.com/api/tasks \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Token refresh

Access tokens expire after 24 hours. Use the refresh token to obtain a new pair without re-authenticating:

curl -X POST https://api.orkosi.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "a1b2c3d4e5..."}'

Response:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIs...(new)...",
  "refresh_token": "f6g7h8i9j0...(new)..."
}

Store the new refresh token — each refresh token is single-use.

httpOnly cookies

Browser clients receive an assimetria_jwt httpOnly cookie automatically on login. No manual header management is needed — the browser sends the cookie with every request.

This method is used by the Assimetria OS frontend. API integrations should use Bearer tokens or API keys instead.

Organization API keys

For machine-to-machine integrations, create API keys via Settings > API Keys in the dashboard.

API keys use the format:

Prefix	Environment
osk_live_*	Production
osk_test_*	Sandbox

Pass the key as a Bearer token:

curl https://api.orkosi.com/api/tasks \
  -H "Authorization: Bearer osk_live_abc123..."

API keys do not expire but can be revoked at any time from the dashboard.

Roles and permissions

Role	Description
admin	Full access to all endpoints including user management and settings
member	Read/write access to tasks, agents, and products
viewer	Read-only access

Endpoints that require admin privileges return 403 Forbidden for non-admin users.

Auth endpoints

Method	Path	Description	Auth required
POST	/api/auth/login	Authenticate and obtain tokens	No
POST	/api/auth/refresh	Refresh an expired access token	No (uses refresh token)
POST	/api/auth/register	Create a new user account	No
POST	/api/auth/logout	Invalidate the current session	Yes
POST	/api/auth/forgot-password	Request a password reset email	No
POST	/api/auth/reset-password	Reset password with a reset token	No
GET	/api/auth/me	Get the current authenticated user	Yes

Security best practices

• Store tokens securely. Never expose JWTs in URLs or client-side logs.
• Use HTTPS in production. All api.orkosi.com traffic is encrypted.
• Rotate API keys periodically and revoke any keys that may have been compromised.
• Use the minimum role required. Prefer member or viewer over admin where possible.