API Reference
User Auth

User Auth

JWT-based authentication for the console and custom UIs built on top of the Pharlo.

For server-to-server integrations, use API keys instead — see Authentication. JWT auth is intended for end-user sessions, not automated backends.

Base URL: https://pharlo.io

How it works

  1. Register or log in to receive a JWT token.
  2. Include the token as Authorization: Bearer <token> on every protected request.
  3. Tokens expire after a fixed period — re-call /login to get a fresh one.

JWT tokens identify a user, while API keys identify a workspace client. Use JWT when your integration involves human accounts (console UI, custom admin panels). Use API keys for everything else.

Endpoints

MethodPathAuth requiredDescriptionStatus
POST/api/v1/auth/register—Register a new user, returns JWT201
POST/api/v1/auth/login—Authenticate, returns JWT200
GET/api/v1/auth/meJWTCurrent user profile200
PATCH/api/v1/auth/profileJWTUpdate profile fields200
POST/api/v1/auth/change-passwordJWTChange password200

POST /api/v1/auth/register

Creates a new user account and returns a JWT token immediately — no separate login step required.

Request body

FieldTypeRequiredDescription
emailstringYesMust be a valid email address and unique across the platform
passwordstringYesMinimum 8 characters
namestringYesDisplay name shown in the console

Example request

curl -X POST https://pharlo.io/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-password",
    "name": "Your Name"
  }'

Response 201 Created

FieldTypeDescription
tokenstringJWT token — use this as Authorization: Bearer <token>
user.idUUIDUnique user identifier
user.emailstringRegistered email address
user.namestringDisplay name
{
  "token": "eyJhbGciOiJSUzI1NiJ9...",
  "user": {
    "id": "018e1f3a-7c2b-7000-8f4d-1a2b3c4d5e6f",
    "email": "you@example.com",
    "name": "Your Name"
  }
}

POST /api/v1/auth/login

Authenticates an existing user and returns a fresh JWT token.

Request body

FieldTypeRequiredDescription
emailstringYesRegistered email address
passwordstringYesAccount password

Example request

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

Response 200 OK

{
  "token": "eyJhbGciOiJSUzI1NiJ9..."
}

Pass the token as Authorization: Bearer <token> on all subsequent authenticated requests. Tokens expire after a fixed period — re-call this endpoint to get a new one. There is no refresh token mechanism; re-authentication is required when the token expires.

GET /api/v1/auth/me

Returns the authenticated user's profile.

⚠️

Requires Authorization: Bearer <token> header. Returns 401 if the token is missing or expired.

Example request

curl https://pharlo.io/api/v1/auth/me \
  -H "Authorization: Bearer $JWT_TOKEN"

Response 200 OK

FieldTypeDescription
idUUIDUnique user identifier
emailstringEmail address
namestringDisplay name
localestringPreferred locale code (e.g. en, uk)
timezonestringIANA timezone string (e.g. Europe/Kyiv)
{
  "id": "018e1f3a-7c2b-7000-8f4d-1a2b3c4d5e6f",
  "email": "you@example.com",
  "name": "Your Name",
  "locale": "en",
  "timezone": "Europe/Kyiv"
}

PATCH /api/v1/auth/profile

Updates one or more profile fields for the authenticated user. All fields are optional — only send the fields you want to change.

⚠️

Requires Authorization: Bearer <token> header. Returns 401 if the token is missing or expired.

Request body

FieldTypeRequiredDescription
namestringNoDisplay name
localestringNoLocale code (e.g. en, uk)
timezonestringNoIANA timezone string (e.g. Europe/Kyiv, America/New_York)
avatarUrlstringNoPublicly accessible URL pointing to the user's avatar image

Example request

curl -X PATCH https://pharlo.io/api/v1/auth/profile \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Name", "timezone": "America/New_York"}'

Response 200 OK

Returns the full updated profile object. Same shape as GET /auth/me.

{
  "id": "018e1f3a-7c2b-7000-8f4d-1a2b3c4d5e6f",
  "email": "you@example.com",
  "name": "New Name",
  "locale": "en",
  "timezone": "America/New_York"
}

POST /api/v1/auth/change-password

Changes the authenticated user's password. Requires the current password for verification — this prevents unauthorized changes even if the JWT is compromised.

⚠️

Requires Authorization: Bearer <token> header. Returns 401 if the token is missing or expired.

Request body

FieldTypeRequiredDescription
currentPasswordstringYesThe user's existing password — used to confirm identity
newPasswordstringYesThe new password. Minimum 8 characters

Example request

curl -X POST https://pharlo.io/api/v1/auth/change-password \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"currentPassword": "old-password", "newPassword": "new-password"}'

Response 200 OK

{
  "message": "Password changed successfully"
}

The existing JWT token remains valid until it naturally expires. If you want to invalidate all active sessions immediately after a password change, prompt the user to log in again.

Error responses

Authentication errors

StatusReason
401Missing, malformed, or expired JWT token on a protected endpoint
403Token is valid but the user lacks permission for the action

Validation errors

StatusEndpointReason
400/registerEmail already in use, invalid format, or password too short
400/loginWrong email or password
400/change-passwordcurrentPassword is incorrect, or newPassword is too short
400/profileInvalid timezone value or malformed avatarUrl

All validation errors follow the standard error format:

{
  "error": "Validation failed",
  "details": {
    "email": ["This value is already used."],
    "password": ["This value is too short. It should have 8 characters or more."]
  }
}

See Error Handling for the full list of error codes and how to handle them in your integration.

See also

WebhooksOrganizations & Members