---
layout: docs
page_title: Namespace API Lock
description: Lock the Vault API on a per-namespace basis.
---

# Namespace Lock and Unlock

Vault makes the API available (unlocked) by default for all namespaces. In
this state, Vault can respond to all API/CLI ('API' from here on out) requests
as normal.

A Vault administrator can lock the API for particular namespaces. In this state,
Vault blocks all but a selected few API endpoints from responding to clients
operating in a locked namespace (or a descendant of a locked namespace). The
endpoints that do respond, the exempt paths, are largely the same as the Vault
unauthenticated paths. They are mainly used for checking the status of various
systems (e.g., `sys/health`), or for unlocking the API.

When the API is locked for a particular namespace, it is also locked for all
descendants of that namespace. If the API was already locked for a descendant,
that lock will remain, but Vault must be unlocked for the parent before
unlocking the descendant.

## Why?

Blocking access to much of Vault can be an important break-glass tool in the
event of unexpected behavior.

For HCP Vault, this provides functionality analogous to sealing Vault, without
the Vault administrator requesting that the Managed Service Provider seal/unseal
Vault.

This feature also becomes valuable for secure multitenancy in a variety of Vault
deployment strategies. You can restrict Vault access for just part of an
organization, without affecting adjacent parts of the business. If unexpected
behavior is detected in sub-organization A, an administrator can disable Vault
access for any entity under sub-organization A, without disabling access for
sub-organization B. Once the cause has been identified and resolved, the API can
be unlocked for sub-organization A.

## Locking

The API can be locked by running `vault namespace lock` (or via the API) while
operating in the namespace to lock. Optionally, a subpath can be provided to
lock a descendant of the current namespace.

An unlock key will be returned, which can be used to unlock the API for that
namespace. Preserve this key to unlock the API in the future.

When the API is locked for a namespace, it will also be locked for all
descendants of that namespace. If an authenticated client attempts to access
Vault from a locked namespace, the returned error will inform that client of the
locking namespace.

## Unlocking

The API can be unlocked by running `vault namespace unlock` (or via the API)
while operating in the namespace to unlock. Optionally, a subpath can be
provided to lock a descendant of the current namespace.

In general, an unlock key is required to unlock the API. This is the same as the
unlock key provided when the namespace was locked.

The unlock key requirement can be overriden by using a root token with the
unlock request. In this case, the unlock key does not need to be provided.

When the API is unlocked, it will also be unlocked for all descendants that were
locked with it. If a descendant namespace was previously locked, that lock will
remain in place.

## API Locked Response

If a request is made to a non-exempt path from a locked namespace, e.g. `nsA`,
Vault responds with an HTTP 503: Service Unavailable. It will also produce the
following error:

`API access to this namespace has been locked by an administrator - "nsA" must be unlocked to gain access.`

Similarly, the same error will return if a request is made in a descendant of
`nsA`.

## How does this work with replication?

API Lock status is replicated to all clusters, and observed at all nodes.