Resolving 401 Unauthorized errors when accessing self-hosted Spaces through Upbound Console

Last updated: April 9, 2026

If you're experiencing 401 Unauthorized errors when trying to access your self-hosted Space through the Upbound Console, this is typically caused by incorrect configuration of the --upbound-iam-issuer-url flag in your spaces-router.

Common Symptoms

  • HTTP 401 errors when selecting a self-hosted Space in the Upbound Console

  • Agent logs showing 401 responses for forwarded requests

  • Spaces-router logs indicating "could not authenticate request" with "invalid bearer token" errors

  • Direct access to the Space works, but Console access fails

Root Cause

This issue typically occurs when:

  1. The --upbound-iam-issuer-url flag is configured with multiple values or an incorrect URL

  2. Network connectivity to auth.upbound.io is blocked

  3. The default Upbound IAM issuer URL is overridden incorrectly

Solution

Step 1: Verify auth.upbound.io connectivity

First, ensure your cluster can reach the Upbound authentication service:

kubectl run -n upbound-system curl-test --rm -it --image=curlimages/curl -- \
  curl -sv https://auth.upbound.io/apis/tokenexchange.upbound.io/v1alpha1/.well-known/openid-configuration

If this fails, add auth.upbound.io to your outbound firewall or egress allowlist. Connected Spaces require outbound connectivity to:

  • connect.upbound.io

  • api.upbound.io

  • auth.upbound.io

Step 2: Fix spaces-router-control-plane configuration

Remove any custom --upbound-iam-issuer-url entries from your spaces-router-control-plane container arguments to allow the default value to take effect.

The default value is:

https://auth.upbound.io/apis/tokenexchange.upbound.io/v1alpha1

Your corrected container args should look like:

[
  "--service-node", "mxe-router",
  "--authentication-structured-config-path=/config/auth/config.yaml",
  "--enable-upbound-rbac",
  "--enable-apollo",
  "--authentication-hub-identities",
  "--authorization-hub-rbac"
]

Important: The --upbound-iam-issuer-url flag accepts only a single string value, not an array. If you need custom OIDC configuration (like Dex), configure it in the structured-auth-config ConfigMap instead.

Step 3: Restart the spaces-router pod

After updating the configuration, restart the spaces-router pod to apply the changes:

kubectl rollout restart deployment/spaces-router -n upbound-system

Understanding the Authentication Flow

When accessing a self-hosted Space through the Console:

  1. Users authenticate with the Upbound Console

  2. Console actions are sent as messages to the Upbound Connect service

  3. Your Space's Connect agent polls for messages and fulfills requests

  4. The spaces-router validates tokens using the configured Upbound IAM issuer

The robot token (space-token) is used by the agent to authenticate with Connect, while Console user requests are validated using Upbound IAM tokens against the issuer configured via --upbound-iam-issuer-url.

If the issue persists

If you continue experiencing 401 errors after following these steps, check:

  • The output of the connectivity test from Step 1

  • Updated router logs for any remaining authentication errors

  • That your organization permissions allow Console access to the connected Space