hcengineering/platform · error · ApiError

Unauthorized

Error message

Unauthorized

What it means

withAdminAuthorization extracts the request token and throws ApiError(401, 'Unauthorized') unless the caller is the system account or has extra.admin === 'true'. It is the admin-only gate for datalake routes.

Source

Thrown at services/datalake/pod-datalake/src/middleware.ts:53

    res.setHeader('Connection', 'keep-alive')
    res.setHeader('Keep-Alive', `timeout=${timeout}, max=${max}`)
    next()
  }
}

export const withOptionalAuth = (secure: boolean): RequestHandler => {
  return secure
    ? withAuthorization
    : (req: Request, res: Response, next: NextFunction) => {
        next()
      }
}

export const withAdminAuthorization = (req: RequestWithAuth, res: Response, next: NextFunction): void => {
  try {
    const token = extractToken(req.headers)
    if (token == null || !(token.account === systemAccountUuid || token.extra?.admin === 'true')) {
      throw new ApiError(401, 'Unauthorized')
    }
    req.token = token

    next()
  } catch (err: any) {
    next(err)
  }
}

export const withAuthorization = (req: RequestWithAuth, res: Response, next: NextFunction): void => {
  try {
    const token = extractToken(req.headers)
    if (token == null || token.extra?.guest === 'true' || token.extra?.readonly === 'true') {
      throw new ApiError(401, 'Unauthorized')
    }
    req.token = token

    next()

View on GitHub (pinned to 63e28dc964)

Solutions

1. Obtain and send a token whose extra.admin is 'true' (or use the system account) for admin routes
2. Re-issue/refresh the token after granting admin so the claim is present
3. Verify the Authorization header format matches extractToken's expectations
4. Confirm you are hitting the right endpoint — use non-admin endpoints where possible

Example fix

// before (regular user token)
Authorization: Bearer eyJ..."extra":{"guest":"false"}
// after (admin token)
Authorization: Bearer eyJ..."extra":{"admin":"true"}

// inspect token claims before calling admin endpoints
const payload = decodeJwt(token)
if (payload.extra?.admin !== 'true' && payload.account !== SYSTEM_ACCOUNT) {
  throw new Error('Admin token required for this datalake operation')
}

function isAdminToken(t: { account?: string, extra?: Record<string, string> } | null): boolean {
  return t != null && (t.account === systemAccountUuid || t.extra?.admin === 'true')
}

try {
  await datalake.adminOperation(...)
} catch (err) {
  if (err.response?.status === 401) {
    // request an admin-scoped token or surface 'admin privileges required'
  } else throw err
}

When it happens

Trigger: Request to an admin-gated datalake route with no token, a non-admin user token, or a token whose extra claims lack admin='true'.

Common situations: Regular service/user tokens used against admin endpoints; token issued before the account was promoted to admin; missing or stale token claims after a permission change; header omitted entirely.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Unauthorized
• account.status.Forbidden
• ApiError
• Invalid auth token
• Token error

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/4a13380f0c765739. Report an issue: GitHub.