Kubo RPC Access Denied: Please provide a valid authorization

Error message

Kubo RPC Access Denied: Please provide a valid authorization token as defined in the API.Authorizations configuration.

What it means

The commands RPC middleware enforces API.Authorizations access control: if the request carries no valid authorization token matching the configured policy, the server responds 403 with this message. It protects the /api/v0/ RPC surface from unauthenticated access when Authorizations are configured.

Source

Thrown at core/corehttp/commands.go:196

		authorizationHeader := r.Header.Get("Authorization")
		auth, ok := authorizations[authorizationHeader]

		if ok {
			// version check is implicitly allowed
			if r.URL.Path == "/api/v0/version" {
				next.ServeHTTP(w, r)
				return
			}
			// everything else has to be safelisted via AllowedPaths
			for _, prefix := range auth.AllowedPaths {
				if strings.HasPrefix(r.URL.Path, prefix) {
					next.ServeHTTP(w, r)
					return
				}
			}
		}

		http.Error(w, "Kubo RPC Access Denied: Please provide a valid authorization token as defined in the API.Authorizations configuration.", http.StatusForbidden)
	})
}

// CommandsOption constructs a ServerOption for hooking the commands into the
// HTTP server. It will NOT allow GET requests.
func CommandsOption(cctx oldcmds.Context) ServeOption {
	return commandsOption(cctx, corecommands.Root)
}

// CheckVersionOption returns a ServeOption that checks whether the client ipfs version matches. Does nothing when the user agent string does not contain `/kubo/` or `/go-ipfs/`
func CheckVersionOption() ServeOption {
	daemonVersion := version.ApiVersion

	return func(n *core.IpfsNode, l net.Listener, parent *http.ServeMux) (*http.ServeMux, error) {
		mux := http.NewServeMux()
		parent.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
			if strings.HasPrefix(r.URL.Path, APIPath) {
				cmdqry := r.URL.Path[len(APIPath):]

View on GitHub (pinned to 329838acdf)

Solutions

Add the correct Authorization header/token as defined in API.Authorizations on the daemon.
Re-read the current token after config changes: `ipfs config API.Authorizations`.
Ensure proxies/gateways forward the Authorization header to the daemon.
If this node is on a trusted private network only, remove/simplify API.Authorizations deliberately (with the security trade-off understood).

Example fix

// before
curl http://127.0.0.1:5001/api/v0/id
// after
curl -H "Authorization: Bearer <token-from-API.Authorizations>" http://127.0.0.1:5001/api/v0/id

Defensive patterns

Strategy: try-catch

Validate before calling

authCfg, _ := ipfsConfigFromPath(ipfsPath)
if len(authCfg.API.Authorizations) > 0 && authToken == "" {
	return errors.New("daemon requires an API token; set Authorization header")
}

Try / catch

resp, err := httpClient.Post("http://127.0.0.1:5001/api/v0/id", "", nil)
if err != nil {
	return err
}
if resp.StatusCode == http.StatusForbidden {
	return errors.New("RPC access denied: refresh the API.Authorizations token")
}

Prevention

Read the token from the daemon config at client startup, not from a hardcoded copy
Rotate tokens in clients at the same time as config changes
Verify proxies forward the Authorization header to kubo
Handle 403 distinctly from other HTTP errors so operators see an auth problem, not a generic failure

When it happens

Trigger: Calling any /api/v0/ endpoint without the required bearer/authorization token configured under API.Authorizations, or with an expired/incorrect token, while the daemon has Authorizations configured.

Common situations: Old scripts and clients predating Authorizations hitting a hardened daemon, tokens rotated in config but not in the calling service, reverse proxies stripping Authorization headers before they reach kubo.

Understand the failure class

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

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/0249097713a3f1d4. Report an issue: GitHub.