hcengineering/platform · error · HttpError

Unauthorized

Error message

Unauthorized

What it means

withAdminAuthorization extracts the auth token from request headers and requires either the system account UUID or extra.admin === 'true'. If no token is present or neither admin condition holds, it throws HttpError 401 'Unauthorized'.

Source

Thrown at pods/preview/src/middleware.ts:45

export interface RequestWithAuth extends Request {
  token?: Token
}

export const keepAlive = (options: KeepAliveOptions): RequestHandler => {
  const { timeout, max } = options
  return (req: Request, res: Response, next: NextFunction) => {
    res.setHeader('Connection', 'keep-alive')
    res.setHeader('Keep-Alive', `timeout=${timeout}, max=${max}`)
    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 HttpError(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 HttpError(401, 'Unauthorized')
    }
    req.token = token

    next()

View on GitHub (pinned to 63e28dc964)

Solutions

1. Send a valid Authorization header with a token that has extra.admin === 'true'
2. Use the system account token for service-to-service admin calls
3. Verify the token was issued with the admin claim (re-authenticate/refresh if needed)
4. Confirm extractToken is parsing your header scheme (Bearer vs raw token) correctly

Example fix

// before
fetch('/admin', { method: 'POST' })
// after
fetch('/admin', { method: 'POST', headers: { Authorization: 'Bearer ' + adminToken } })

const token = parseToken(getAuthorizationHeader())
const isAdmin = token != null && (token.account === systemAccountUuid || token.extra?.admin === 'true')
if (!isAdmin) throw new HttpError(401, 'Unauthorized')

function isAdminToken (t: unknown): t is { account: string; extra?: { admin?: string } } {
  const tok = t as any
  return tok != null && (tok.account === systemAccountUuid || tok.extra?.admin === 'true')
}

try {
  await callAdminEndpoint()
} catch (err) {
  if (err.status === 401 || err.message === 'Unauthorized') {
    await refreshAdminCredentials()
    // retry once or surface a clear 'admin privileges required' message
  } else throw err
}

When it happens

Trigger: Any request to an admin-protected endpoint where extractToken returns null (missing/invalid Authorization header) or the token's account is not the system account and token.extra.admin !== 'true'.

Common situations: Client omitted the Authorization header; expired/invalid token failed extraction; regular user token lacking admin claim calling admin endpoints; service-to-service calls not using the system account token.

Understand the failure class

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

Related errors

• Unauthorized
• Invalid workspace login info by token
• Invalid workspace
• Not an owner of workspace
• err.message

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