Authentication

All API requests to Nacho API require authentication using an API key.

API Key Format

API keys follow this format:

napi_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• Prefix: napi_ (Nacho API)
• Key: 32 character random string

Authenticating Requests

HTTP Header (Recommended)

Pass your API key in the apikey header:

curl -X POST https://api.nacho.builders/v1/ogmios \
-H "Content-Type: application/json" \
-H "apikey: napi_your_key_here" \
-d '{"jsonrpc": "2.0", "method": "queryNetwork/tip"}'

WebSocket Authentication

For WebSocket connections, pass the API key as a query parameter:

wss://api.nacho.builders/v1/ogmios?apikey=napi_your_key_here

const ws = new WebSocket(
'wss://api.nacho.builders/v1/ogmios?apikey=napi_your_key_here'
);

ws.onopen = () => {
ws.send(JSON.stringify({
  jsonrpc: '2.0',
  method: 'queryNetwork/tip'
}));
};

ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log(data.result);
};

API Key Security

Best Practices:

1. Use Environment Variables

   export NACHO_API_KEY=napi_your_key_here

2. Use a Secrets Manager in production (AWS Secrets Manager, HashiCorp Vault, etc.)

3. Rotate Keys periodically via the API Keys dashboard

4. Use Separate Keys for development, staging, and production

Rate Limits

Rate limits apply to both HTTP requests and WebSocket messages:

HTTP Rate Limit Response

{
  "error": {
    "code": 429,
    "message": "Rate limit exceeded. Please slow down."
  }
}

WebSocket Rate Limit Response

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32029,
    "message": "Rate limit exceeded. Please slow down.",
    "data": { "retryAfter": 1000, "remaining": 0 }
  },
  "id": "request-id"
}

Error Responses

Invalid API Key

{
  "error": {
    "code": 401,
    "message": "Invalid API key"
  }
}

Missing API Key

{
  "error": {
    "code": 401,
    "message": "API key required"
  }
}

Inactive Key

{
  "error": {
    "code": 403,
    "message": "API key is inactive"
  }
}

Managing API Keys

You can manage your API keys in the dashboard:

• Create new PAID tier keys
• Revoke compromised keys
• View usage statistics per key
• Rename keys for organization