Authentication Guide

Complete guide to authenticating with the Cred Protocol API

Overview

This guide covers everything you need to know about authenticating with the Cred Protocol API, from creating API keys to implementing secure authentication in your applications.

Authentication Methods

The Cred Protocol API supports two authentication methods:

1. API Key Authentication (Recommended)

The standard authentication method using Bearer tokens. Every request includes your API key in the Authorization header. Usage is tracked against your subscription’s Cred Unit balance.

Authorization: Bearer YOUR_API_KEY

2. x402 Payment Authentication (No Account Required)

For instant access without creating an account, you can pay per request using USDC stablecoins via the x402 protocol. This enables accountless API access with immediate settlement.

X-PAYMENT: <signed_payment_payload>

x402 payments support USDC on Base and SKALE networks. Facilitators include the Coinbase Developer Platform (CDP) for Base and the dirtroad.dev facilitator for SKALE.

Creating API Keys

Step-by-Step Guide

1. Sign In

   Go to app.credprotocol.com and sign in to your account.

2. Navigate to Dashboard

   Click on Dashboard in the navigation menu.

3. Access API Keys

   Find the API Keys section in your dashboard.

4. Create New Key

   Click Create API Key and enter a descriptive name for your key.

   Use descriptive names like “Production Server”, “Development”, or “CI/CD Pipeline” to easily identify keys later.

5. Copy and Store Securely

   Copy your API key immediately and store it securely. You won’t be able to view the full key again.

   Never share your API key or commit it to version control.

Implementation Examples

Environment Variables

Always store your API key in environment variables:

.env

CRED_API_KEY=your_api_key_here

Backend Proxy Pattern

For web applications, create a backend proxy to keep your API key secure:

Next.js API Route

// pages/api/credit-score.js
export default async function handler(req, res) {
  const { address } = req.query;
  
  const response = await fetch(
    `https://api.credprotocol.com/api/v2/score/address/${address}`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.CRED_API_KEY}`
      }
    }
  );
  
  const data = await response.json();
  res.status(response.status).json(data);
}

SDK Pattern

Create a reusable client for your application:

// lib/cred-client.ts
class CredClient {
  private apiKey: string;
  private baseUrl = 'https://api.credprotocol.com';

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  private async request(endpoint: string) {
    const response = await fetch(`${this.baseUrl}${endpoint}`, {
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      }
    });

    if (!response.ok) {
      throw new Error(`API Error: ${response.status}`);
    }

    return response.json();
  }

  async getScore(address: string) {
    return this.request(`/api/v2/score/address/${address}`);
  }

  async getReport(address: string) {
    return this.request(`/api/v2/report/address/${address}`);
  }

  async getIdentity(address: string) {
    return this.request(`/api/v2/identity/address/${address}/attestations`);
  }
}

// Usage
const cred = new CredClient(process.env.CRED_API_KEY!);
const score = await cred.getScore('vitalik.eth');

Security Best Practices

Never expose keys in client-side code

API keys should never be included in frontend JavaScript, mobile apps, or anywhere they can be viewed by end users.

// ❌ NEVER do this
const response = await fetch('https://api.credprotocol.com/api/v2/score/address/vitalik.eth', {
  headers: { 'Authorization': 'Bearer sk_live_abc123' }
});

// ✅ Call your backend instead
const response = await fetch('/api/credit-score?address=vitalik.eth');

Use environment variables

Store API keys in environment variables, never in code:

• Use .env files for local development
• Use secret management services in production (AWS Secrets Manager, HashiCorp Vault, etc.)
• Never commit .env files to version control

Rotate keys regularly

Establish a key rotation schedule:

1. Create a new API key
2. Update your application to use the new key
3. Verify the new key works in production
4. Revoke the old key

Use separate keys for environments

Create different API keys for:

• Development
• Staging
• Production

This limits the impact if a key is compromised and makes auditing easier.

Monitor key usage

Regularly review your API usage in the Dashboard to:

• Detect unusual activity patterns
• Identify compromised keys
• Optimize your usage

Troubleshooting

Common Errors

401 Unauthorized

{ "detail": "Invalid or missing API key" }

Possible causes:

• API key is missing from the request
• API key is malformed
• API key has been revoked

Solutions:

• Verify the Authorization header is present
• Check for typos in the API key
• Ensure you’re using Bearer prefix (with space)
• Create a new API key if needed

403 Forbidden

{ "detail": "Insufficient permissions" }

Possible causes:

• Accessing a feature not included in your plan
• Rate limit exceeded

Solutions:

• Check your plan limits in the Dashboard
• Upgrade your plan if needed
• Implement rate limiting in your application

Testing Your API Key

Use this simple test to verify your API key is working:

curl -X GET "https://api.credprotocol.com/users/me" \
  -H "Authorization: Bearer YOUR_API_KEY"

A successful response confirms your key is valid:

{
  "id": "uuid",
  "email": "[e-mail]",
  "is_active": true
}

x402 Payment Authentication

The x402 protocol enables instant API access by paying per request with USDC. This is ideal for:

• Testing the API before committing to a subscription
• Low-volume usage where a subscription isn’t cost-effective
• Programmatic access from applications that can’t store API keys
• Instant access without account creation or approval delays

How It Works

1. Make a request without authentication
2. Receive a 402 Payment Required response with payment details
3. Sign a USDC transfer authorization using your wallet
4. Retry the request with the signed payment in the X-PAYMENT header
5. Receive your API response (payment settles automatically)

Payment Required Response

When you make a request without authentication, you’ll receive:

{
  "error": "authentication_required",
  "message": "This endpoint requires authentication. Choose one of the following methods:",
  "cred_units": 1,
  "options": [
    {
      "method": "api_token",
      "description": "Use an API token from your dashboard",
      "header": "Authorization: Bearer YOUR_API_KEY",
      "cost": "1 Cred Units",
      "signup_url": "https://app.credprotocol.com/account/register"
    },
    {
      "method": "x402_payment",
      "description": "Pay per request with USDC (no account required)",
      "header": "X-PAYMENT: <signed_payment>",
      "price": "$0.01",
      "currency": "USDC",
      "network": "base",
      "pay_to": "0x..."
    }
  ]
}

The response includes an X-PAYMENT-REQUIRED header with base64-encoded payment requirements that x402-compatible wallets can process automatically.

Pricing

x402 payments use the same pricing as Cred Units at $0.01 per Cred Unit:

Operation	Cred Units	x402 Price
Credit Score	1 CU	$0.01
Full Report	7 CUs	$0.07
Enhanced Report	10 CUs	$0.10

Supported Networks

Network	Chain ID	Type	USDC Token
Base	8453	Mainnet	USD Coin
Base Sepolia	84532	Testnet	USD Coin
SKALE Base	1187947933	Mainnet	Bridged USDC (SKALE Bridge)
SKALE Base Sepolia	324705682	Testnet	Bridged USDC (SKALE Bridge)

SKALE offers zero-gas transactions with sub-second finality, making it ideal for high-frequency micropayments.

Integration

For detailed integration instructions, see the x402 documentation from Coinbase Developer Platform.

JavaScript (x402 SDK)

import { x402Client } from 'x402';

const client = new x402Client({
  wallet: yourWallet,
  network: 'base'
});

// The client automatically handles 402 responses
const response = await client.fetch('https://api.credprotocol.com/api/v2/score/address/vitalik.eth');
const data = await response.json();