Authentication API

Overview

The Authentication API provides endpoints to sign users in, register new users, and refresh authentication tokens. Each endpoint returns session/token information that clients should use to authenticate subsequent API requests.

Base path: /api/v1/auth

Response envelope

Most API endpoints in this project return a consistent envelope. Authentication endpoints return the session/token information in the data object when successful.

{
  "success": true,
  "message": "optional human readable message",
  "data": { /* payload shown per endpoint*/ },
  "error": "error text"
}

Notes about tokens

• access_token is a Bearer JWT. Include it on protected API requests using the Authorization: Bearer <access_token> header.
• refresh_token can be used to obtain a new access token via the refresh endpoint below. A refresh token is returned on successful authentication when applicable.
• Administrative user-management endpoints exist for service integrations; they require elevated credentials and should only be used by trusted services.

POST /api/v1/auth/login

Authenticate a user using email and password and return a session with tokens.

Request

• Content-Type: application/json

Body

{
  "email": "user@example.com",
  "password": "password123"
}

Success response (200)

{
  "success": true,
  "message": "Authentication successful",
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "...",
    "expires_at": 1735689600,
    "expires_in": 3600,
    "user": {
      "id": "8b4cdb8d-...",
      "email": "user@example.com",
      "created_at": "2025-11-13T10:00:00Z"
    }
  }
}

Common errors

• 400 Bad Request — invalid body (missing/invalid email or password)
• 401 Unauthorized — invalid credentials or sign-in failure
• 500 Internal Server Error — unexpected error (check server logs)

Example curl

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

POST /api/v1/auth/signup

Create a new user and return a session when available. This endpoint registers a new user account and, depending on account confirmation settings, may return an active session.

Request

• Content-Type: application/json

Body (example)

{
  "email": "newuser@example.com",
  "password": "SecretPass123!"
}

Success response (200)

{
  "success": true,
  "message": "Authentication successful",
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "...",
    "expires_at": 1735689600,
    "expires_in": 3600,
    "user": {
      "id": "f47ac10b-...",
      "email": "newuser@example.com",
      "created_at": "2025-11-13T10:00:00Z"
    }
  }
}

Notes

• Depending on account confirmation settings (for example, if email confirmation is required), a session may or may not be returned immediately.
• Administrative create and management flows are available via the admin API and require elevated credentials; use them only in trusted service contexts.

Common errors

• 400 Bad Request — invalid body
• 409 Conflict — email already registered (propagated from Auth)
• 500 Internal Server Error — unexpected error

Example curl

curl -X POST "https://phy.engineering/api/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{"email":"newuser@example.com","password":"SecretPass123!"}'

POST /api/v1/auth/refresh

Exchange a refresh token for a new session (new access token and refresh token).

Request

• Content-Type: application/json

Body

{
  "refresh_token": "<refresh-token-from-login-or-signup>"
}

Success response (200)

{
  "success": true,
  "message": "Token refreshed",
  "data": {
    "access_token": "eyJhbGci...",
    "refresh_token": "...",
    "expires_at": 1735689600,
    "user": {
      "id": "8b4cdb8d-...",
      "email": "user@example.com",
      "created_at": "2025-11-13T10:00:00Z"
    }
  }
}

Common errors

• 400 Bad Request — invalid body
• 401 Unauthorized — invalid or expired refresh token
• 500 Internal Server Error — unexpected error

Example curl

curl -X POST "https://phy.engineering/api/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"<refresh-token>"}'

GET /api/v1/auth/organizations

List organizations the authenticated user belongs to along with the user's role in each.

Authentication: Requires a valid access token (Bearer).

Request

• Method: GET
• Path: /api/v1/auth/organizations

Success response (200)

{
  "success": true,
  "message": "Retrieved 2 organizations",
  "data": [
    {
      "id": "8b4cdb8d-...",
      "name": "Example Utilities",
      "is_personal_account": false,
      "role": "ADMIN"
    },
    {
      "id": "a17ac10b-...",
      "name": "Personal Account",
      "is_personal_account": true,
      "role": "OWNER"
    }
  ],
  "count": 2
}

Common errors

• 401 Unauthorized — missing or invalid access token
• 500 Internal Server Error — unexpected error

Example curl

curl -X GET "https://phy.engineering/api/v1/auth/organizations" \
  -H "Authorization: Bearer <access_token>"

GET /api/v1/auth/users/:userId/organizations

List organizations for a specified user Id. This allows administrative or service contexts to retrieve organization memberships for any user that is visible under access policies. Visibility is subject to authorization rules; only organizations the requester is permitted to view will be returned.

Authentication: Requires a valid access token (Bearer).

Path parameter

• userId (uuid)

Success response (200)

{
  "success": true,
  "message": "Retrieved 3 organizations for user",
  "data": [
    {
      "id": "8b4cdb8d-...",
      "name": "Example Utilities",
      "is_personal_account": false,
      "role": "ADMIN",
      "user_id": "f47ac10b-...",
      "requested_by": "8b4cdb8d-..."
    }
  ],
  "count": 3
}

Common errors

• 400 Bad Request — invalid userId format
• 401 Unauthorized — missing or invalid access token
• 500 Internal Server Error — unexpected error

Example curl

curl -X GET "https://phy.engineering/api/v1/auth/users/<user-id>/organizations" \
  -H "Authorization: Bearer <access_token>"