Authentication

Every request to the Bitcoin API on TheRPC needs an API key. A self-hosted bitcoind would make you manage rpcuser/rpcpassword HTTP Basic credentials, a cookie file, and an rpcallowip list. TheRPC fronts the Bitcoin Core RPC for you and replaces all of that with a single API key tied to your account — you get a maintained, public-facing endpoint at https://bitcoin.therpc.io/YOUR_API_KEY without running or securing a node yourself. This guide walks through getting a key from your dashboard, the two ways to send it (URL path or Bearer header), securing it, loading it from the environment, and recognizing an authentication failure.

Getting an API Key

• Sign up for a free account at TheRPC.io.
• Open your Dashboard after signing in.
• Go to the API Keys section.
• Click Generate key — your new key appears and is ready to drop into the https://bitcoin.therpc.io/YOUR_API_KEY endpoint.

Using Your API Key

There are two ways to present your key, and you only need one of them per request. The simplest is to put the key straight in the URL path: https://bitcoin.therpc.io/YOUR_API_KEY. This is handy for curl one-liners and for thin Bitcoin RPC clients that take a single connection URL. Alternatively, send the key as a Bearer token in the Authorization header (Authorization: Bearer YOUR_API_KEY), which keeps it out of logged URLs and proxy access logs. Whichever you choose, every request must carry the key one of these two ways — an unauthenticated request is rejected.

API Key in URL Path

1https://bitcoin.therpc.io/YOUR_API_KEY

HTTP Headers

1Authorization: Bearer YOUR_API_KEY

Example Requests — curl

1curl --request POST 'https://bitcoin.therpc.io/YOUR_API_KEY' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_KEY' \
4  --data '{
5    "jsonrpc": "1.0",
6    "id": "therpc",
7    "method": "getblockcount",
8    "params": []
9  }'

Example Requests — JavaScript

1const response = await fetch('https://bitcoin.therpc.io/YOUR_API_KEY', {
2  method: 'POST',
3  headers: {
4    'Content-Type': 'application/json',
5    Authorization: `Bearer ${API_KEY}`,
6  },
7  body: JSON.stringify({
8    jsonrpc: '1.0',
9    id: 'therpc',
10    method: 'getblockcount',
11    params: [],
12  }),
13});

Security Best Practices

• Never commit keys to source control. Keep them out of git; add .env to .gitignore so a key never lands in a public or shared repo.
• Don't paste keys into public forums or chats. A key in a support thread, screenshot, or Discord message should be treated as leaked and revoked.
• Store keys in environment variables or a secret vault rather than hardcoding them in source — see the .env examples below.
• Rotate keys periodically, and revoke a compromised key immediately from the dashboard, then generate a fresh one.
• Use a separate key per environment or application (dev, staging, production) so you can revoke one without breaking the others.
• Monitor key usage in the dashboard to spot unexpected spikes — often the first sign a key has leaked.

Error Handling

When authentication fails, TheRPC returns a JSON-RPC error in the standard envelope: result is null and error carries a code and an "Invalid authentication credentials" message, as shown below. The usual causes are a missing key (no key in the path and no Authorization header), a malformed or mistyped key, an expired or revoked key (regenerate it in the dashboard), or, when the credentials are valid but you've sent too many requests, a rate-limit rejection — see the Rate Limits guide for that case.

Authentication Error Response

1{
2  "result": null,
3  "error": {
4    "code": -32001,
5    "message": "Invalid authentication credentials"
6  },
7  "id": "therpc"
8}

Environment Setup

Load your key from an environment variable rather than writing it into source. Keep it in a .env file (ignored by git) and read it at startup, building the Bitcoin endpoint URL from the key as shown below. This keeps the secret out of your codebase and lets you swap keys per environment without code changes.

Environment Variables — .env

1# .env file
2THERPC_API_KEY=your_api_key_here

Configuration Examples — Node.js

1require('dotenv').config();
2const API_KEY = process.env.THERPC_API_KEY;
3const ENDPOINT = `https://bitcoin.therpc.io/${API_KEY}`;

Configuration Examples — Python

1import os
2from dotenv import load_dotenv
3 
4load_dotenv()
5API_KEY = os.getenv('THERPC_API_KEY')
6ENDPOINT = f"https://bitcoin.therpc.io/{API_KEY}"