API Key Authentication All API endpoints require authentication using a Bearer token. You must include your API key in the Authorization header of every request.
Getting Your API Key
Add on Discord
Add southctrl on Discord
Request Access
Send a message requesting API access
Receive Your Key
You’ll receive your unique API key via Discord DM
Store Securely
Save your API key in a secure location (environment variables recommended)
API keys are issued manually to ensure quality and prevent abuse. You should receive your key within 24 hours.
Include your API key in every request using the Authorization header:
Authorization: Bearer YOUR_API_KEY
Example Requests cURL
JavaScript
Python
Node.js (axios)
curl -X GET "https://rocks.rive.wtf/api/bible/random?translation=web" \ -H "Authorization: Bearer YOUR_API_KEY"
Using Environment Variables Never hardcode your API key in your code! Always use environment variables to keep your key secure.
Node.js
Python
Discord.js Bot
// .env file ROCKS_API_KEY = your_api_key_here // In your code require ( 'dotenv' ). config (); const API_KEY = process . env . ROCKS_API_KEY ; const response = await fetch ( 'https://rocks.rive.wtf/api/endpoint' , { headers: { 'Authorization' : `Bearer ${ API_KEY } ` } });
# .env file ROCKS_API_KEY = your_api_key_here # In your code import os from dotenv import load_dotenv load_dotenv() API_KEY = os.getenv( 'ROCKS_API_KEY' ) headers = { 'Authorization' : f 'Bearer { API_KEY } ' } response = requests.get( 'https://rocks.rive.wtf/api/endpoint' , headers = headers)
// config.json (DO NOT commit to git) { "token" : "your_discord_bot_token" , "rocksApiKey" : "your_api_key_here" } // In your bot const config = require ( './config.json' ); const response = await fetch ( 'https://rocks.rive.wtf/api/endpoint' , { headers: { 'Authorization' : `Bearer ${ config . rocksApiKey } ` } });
Security Best Practices
Environment Variables Always store API keys in environment variables, never in source code
Gitignore Files Add .env and config files containing keys to .gitignore
Server-Side Only Never expose API keys in client-side JavaScript or public repositories
Rotate Regularly Contact southctrl on Discord if you need to rotate your API key
Important Security Notes:
Never commit API keys to version control (Git, GitHub, etc.)
Don’t share your API key in Discord servers, forums, or public channels
If you accidentally expose your key, contact southctrl immediately for a new one
Use different keys for development and production environments when possible
Rate Limiting The API implements rate limiting to ensure fair usage across all users:
Standard: 100 requests per minuteBurst: 10 requests per second If you need higher limits, contact southctrl on Discord with your use case.
Implement exponential backoff when you receive a 429 status: async function makeRequestWithRetry ( url , retries = 3 ) { for ( let i = 0 ; i < retries ; i ++ ) { const response = await fetch ( url , { headers: { 'Authorization' : `Bearer ${ API_KEY } ` } }); if ( response . status !== 429 ) { return response . json (); } // Wait before retrying (exponential backoff) await new Promise ( resolve => setTimeout ( resolve , 1000 * Math . pow ( 2 , i ))); } throw new Error ( 'Rate limit exceeded' ); }
Error Responses If authentication fails, you’ll receive one of the following error responses:
Status Code Description Solution 401 Missing or invalid API key Check that your API key is correct and properly formatted 403 API key doesn’t have permission Contact southctrl if you need access to this endpoint 429 Rate limit exceeded Wait before making more requests or implement rate limiting 500 Server error Try again later or contact support if issue persists
Example Error Response { "success" : false , "error" : { "code" : 401 , "message" : "Invalid or missing API key" , "details" : "Please provide a valid API key in the Authorization header" } }
Testing Your Authentication Use this simple test to verify your API key is working:
curl -X GET "https://rocks.rive.wtf/api/bible/random?translation=web" \ -H "Authorization: Bearer YOUR_API_KEY" \ -w "\nStatus: %{http_code}\n"
Need Help?
Contact Support Discord: southctrlFor issues with authentication, API key requests, or if you believe your key has been compromised, contact southctrl directly on Discord.
Keep your API key secure and treat it like a password. Anyone with your API key can make requests on your behalf.
