API Documentation

Complete guide to integrating KeyClaim Challenge Validation API into your application

Overview

KeyClaim provides a simple API for challenge-response validation. No authentication systems, no dashboards, just API validation. Perfect for building secure applications without the complexity.

Base URL

Download Postman Collection
https://keyclaim.org

The Postman collection includes all API endpoints with example requests. Import it into Postman to get started quickly.

1

Create Challenge

Generate a new challenge token for validation. Each challenge is unique and expires after the specified TTL.

POST/api/challenge/create

cURL (Copy to Postman)

curl -X POST https://keyclaim.org/api/challenge/create \
  -H "Content-Type: application/json" \
  -d '{
    "key": "kc_your_api_key_here",
    "ttl": 30
  }'

Request Body

{
  "key": "kc_your_api_key_here",
  "ttl": 30
}

Response

{
  "challenge": "random_hex_string",
  "expires_in": 30
}

Code Examples

curl -X POST https://keyclaim.org/api/challenge/create \
  -H "Content-Type: application/json" \
  -d '{
    "key": "kc_your_api_key_here",
    "ttl": 30
  }'
2

Validate Response

Validate a challenge-response pair. Returns validation result and optional signature for Pro/Business plans.

POST/api/challenge/validate

cURL (Copy to Postman)

curl -X POST https://keyclaim.org/api/challenge/validate \
  -H "Content-Type: application/json" \
  -d '{
    "key": "kc_your_api_key_here",
    "challenge": "challenge_from_create",
    "response": "hmac_sha256_response_here"
  }'

Request Body

{
  "key": "kc_your_api_key_here",
  "challenge": "challenge_from_create",
  "response": "response_value"
}

Response

{
  "valid": true,
  "signature": "signed_verdict_hex"
}

Response Generation Examples

curl -X POST https://keyclaim.org/api/challenge/validate \
  -H "Content-Type: application/json" \
  -d '{
    "key": "kc_your_api_key_here",
    "challenge": "challenge_from_create",
    "response": "hmac_sha256_response_here"
  }'

Error Codes

invalid_key

API key is invalid or inactive

expired_challenge

Challenge has expired

replayed_challenge

Challenge has already been used

invalid_signature

Response signature is invalid

rate_limited

Rate limit exceeded

RSA Public-Private Key Encryption

Enhance security with RSA encryption! Generate a key pair, keep the private key on your client, and let the server encrypt challenges with your public key. Perfect for maximum MITM protection.

How It Works

  • • Generate public-private key pair
  • • Keep private key on client (never send to server)
  • • Server encrypts challenges with public key
  • • Client decrypts with private key
  • • Continue with normal HMAC validation

Benefits

  • • Encrypted challenges (useless if intercepted)
  • • Enhanced MITM protection
  • • Forward secrecy
  • • Works with all platforms

⚠️ Important: Your private key must be kept secure on the client side. Never send it to the server or commit it to version control.

View Complete RSA Key Pair Guide →

Response Generation (Backend Keys)

For backend API keys, you need to generate a response using HMAC-SHA256. The response must be computed from the challenge using your API key as the secret.

For Testing

Use the playground to test responses

For Production

Use HMAC-SHA256(challenge, apiKey)

View Response Generation Guide →

Platform Guides

Learn how to integrate KeyClaim in your preferred platform:

Web Frameworks

Mobile Platforms

Backend Documentation

Learn how to integrate KeyClaim in your preferred programming language:

Node.js

Node.js

JavaScript/TypeScript integration guide

View Guide →
Python

Python

Python 3.7+ integration guide

View Guide →
PHP

PHP

PHP 7.4+ integration guide

View Guide →
Java

Java

Java 8+ integration guide

View Guide →
Kotlin

Kotlin

Kotlin/JVM integration guide

View Guide →
C#

C#

.NET/C# integration guide

View Guide →
Go

Go

Go 1.18+ integration guide

View Guide →