API Documentation

Integrate decentralized identity verification into your application with our comprehensive API. Build the future of identity verification.

Quick Start

Get started with Keystone API in just a few lines of code. Check if a user is verified:

// Check if user is verified
const response = await fetch(
  'https://your-backend-url.com/simple-status?address=0x1234...'
);
const { isVerified } = await response.json();
console.log('User verified:', isVerified);// Check if user is verified
const response = await fetch(
  'https://your-backend-url.com/simple-status?address=0x1234...'
);
const { isVerified } = await response.json();
console.log('User verified:', isVerified);

API Endpoints

Simple Status Check

GET/simple-status

Check if a user has any verified identity without requiring signature.

Parameters:

• address (required): User's wallet address

Response:

{
  "isVerified": true,
  "cid": "QmXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx"
}{
  "isVerified": true,
  "cid": "QmXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXxXx"
}

Get All Verifications

GET/verifications

Retrieve all verification types for a user with consent checking.

Parameters:

• address (required): User's wallet address
• requestedBy (optional): Your app identifier

Response:

{
  "walletAddress": "0x1234...",
  "verifications": [
    {
      "verification_type": "student",
      "is_verified": true,
      "consented": true,
      "university": "Stanford University",
      "student_id": "12345678"
    }
  ]
}{
  "walletAddress": "0x1234...",
  "verifications": [
    {
      "verification_type": "student",
      "is_verified": true,
      "consented": true,
      "university": "Stanford University",
      "student_id": "12345678"
    }
  ]
}

Integration Examples

JavaScript/TypeScript

// Check if user is verified
async function checkUserVerification(walletAddress) {
  try {
    const response = await fetch(
      `https://your-backend-url.com/simple-status?address=${walletAddress}`
    );
    const data = await response.json();
    return data.isVerified;
  } catch (error) {
    console.error('Verification check failed:', error);
    return false;
  }
}

// Get all user verifications
async function getUserVerifications(walletAddress, appId) {
  try {
    const response = await fetch(
      `https://your-backend-url.com/verifications?address=${walletAddress}&requestedBy=${appId}`
    );
    const data = await response.json();
    return data.verifications;
  } catch (error) {
    console.error('Failed to fetch verifications:', error);
    return [];
  }
}

// Check specific verification type
async function checkStudentStatus(walletAddress) {
  const verifications = await getUserVerifications(walletAddress, 'myapp');
  const studentVerification = verifications.find(v => v.verification_type === 'student');
  return studentVerification?.is_verified && studentVerification?.consented;
}// Check if user is verified
async function checkUserVerification(walletAddress) {
  try {
    const response = await fetch(
      `https://your-backend-url.com/simple-status?address=${walletAddress}`
    );
    const data = await response.json();
    return data.isVerified;
  } catch (error) {
    console.error('Verification check failed:', error);
    return false;
  }
}

// Get all user verifications
async function getUserVerifications(walletAddress, appId) {
  try {
    const response = await fetch(
      `https://your-backend-url.com/verifications?address=${walletAddress}&requestedBy=${appId}`
    );
    const data = await response.json();
    return data.verifications;
  } catch (error) {
    console.error('Failed to fetch verifications:', error);
    return [];
  }
}

// Check specific verification type
async function checkStudentStatus(walletAddress) {
  const verifications = await getUserVerifications(walletAddress, 'myapp');
  const studentVerification = verifications.find(v => v.verification_type === 'student');
  return studentVerification?.is_verified && studentVerification?.consented;
}

React Hook

import { useState, useEffect } from 'react';

function useVerificationStatus(walletAddress) {
  const [isVerified, setIsVerified] = useState(false);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    if (!walletAddress) return;

    async function checkStatus() {
      try {
        const response = await fetch(
          `/api/simple-status?address=${walletAddress}`
        );
        const data = await response.json();
        setIsVerified(data.isVerified);
      } catch (error) {
        console.error('Verification check failed:', error);
      } finally {
        setLoading(false);
      }
    }

    checkStatus();
  }, [walletAddress]);

  return { isVerified, loading };
}import { useState, useEffect } from 'react';

function useVerificationStatus(walletAddress) {
  const [isVerified, setIsVerified] = useState(false);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    if (!walletAddress) return;

    async function checkStatus() {
      try {
        const response = await fetch(
          `/api/simple-status?address=${walletAddress}`
        );
        const data = await response.json();
        setIsVerified(data.isVerified);
      } catch (error) {
        console.error('Verification check failed:', error);
      } finally {
        setLoading(false);
      }
    }

    checkStatus();
  }, [walletAddress]);

  return { isVerified, loading };
}

Verification Types

Student Verification

Educational platforms, student discounts

Fields: university, student_id, graduation_year

Identity Verification

Age-restricted services, KYC compliance

Fields: country, is_over_18, document_type

Employment Verification

Professional networks, job platforms

Fields: company, position, salary_range

Address Verification

Financial services, delivery platforms

Fields: address, document_type

Biometric Verification

High-security applications

Fields: biometric_verified, liveness_score

Privacy & Security

Privacy & Consent

User Control

Users control which verifications they share

Decentralized Storage

Data stored on IPFS, not our servers

Revocable Consent

Users can revoke access anytime

Security Features

Signature Verification

Cryptographic proof of user consent

Blockchain Proofs

Immutable verification records

Rate Limiting

Protection against abuse

Error Handling

400 Bad Request

Missing required parameters

401 Unauthorized

Invalid signature

500 Server Error

Server-side error

{
  "error": "address parameter is required"
}{
  "error": "address parameter is required"
}

Ready to Integrate?

Start building with Keystone API today. Join thousands of developers building the future of decentralized identity.