> ## 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

In the challenge editor:

<Steps>
  <Step title="Open the Advanced step" icon="sliders">
    Challenge editor -> Advanced.
  </Step>

  <Step title="Set unlockPrice" icon="key">
    Enter the number of keys required. 1-N. Default: 0 (no gate).
  </Step>

  <Step title="Decide where keys come from" icon="gift">
    Keys are a Nudj currency — members earn them from specific challenges, rewards, or admin gifts. You decide the supply.
  </Step>

  <Step title="Save" icon="save">
    Save the challenge. Members with fewer than `unlockPrice` keys see the gate; others see the unlock prompt.
  </Step>
</Steps>

***

## 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>