> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nudj.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Key-Gated Challenges

> Configure unlock-price (keys) to gate challenges behind an access token or accumulated currency

Key-gated challenges require a member to "spend a key" before starting. It's a simple access-control primitive that unlocks premium, member-only, or VIP-tier content.

## How it works

Each challenge has an **`unlockPrice`** field — the number of keys a member must spend to open it. Zero = open to anyone. Non-zero = requires keys.

When a member opens a gated challenge:

1. Nudj checks the member's key balance.
2. If sufficient, the member is prompted to spend X keys.
3. On confirmation, `unlockPrice` keys are deducted, and the challenge opens.
4. Once unlocked, the member retains access — no re-paying unless the admin resets it.

***

## Configuring the unlock

<Note>
  `unlockPrice` is a challenge data field. There is currently **no control for it in the admin challenge editor** — set it programmatically via the [Admin API](#api) or a data import. New challenges default to `unlockPrice: 0` (no gate).
</Note>

Keys are a Nudj currency — members earn them from specific challenges, rewards, or admin gifts, so plan where the supply comes from. Members with fewer than `unlockPrice` keys see the gate; others see the unlock prompt.

***

## Key economy design

Balancing keys is an economy decision:

<Tip>
  Treat keys as a **scarce resource**. If every challenge earns 2 keys and every unlock costs 1 key, gating means nothing. Target: members need 3-5 normal completions to unlock one gated challenge.
</Tip>

<Tip>
  Use **achievements** to drop keys as milestone rewards — e.g. "complete 10 challenges -> earn 5 keys". Keeps gating aspirational.
</Tip>

***

## API

Programmatic unlocks via `POST /challenges/{id}/unlock` — useful for integrations where keys are earned through external events (e.g. Shopify purchases).

See [Admin API reference](/api-reference/admin).

***

## When to use gating

<AccordionGroup>
  <Accordion title="VIP content" icon="crown">
    Gate high-value challenges behind keys so members earn the right to play.
  </Accordion>

  <Accordion title="Progression ladders" icon="stairs">
    Pair with [achievements as actions](/admin-guide/achievements/achievements-as-actions) to build layered progressions.
  </Accordion>

  <Accordion title="Anti-spam" icon="shield">
    Gate expensive-to-process challenges (large file uploads, AI moderation) behind small unlock prices to reduce spam.
  </Accordion>
</AccordionGroup>

<Warning>
  Don't gate your **onboarding challenge**. New members need a zero-friction first interaction.
</Warning>