All requests to the Bluerails API must be authenticated using your unique Organization ID and secret API key. Requests without valid authentication will fail with a 401 Unauthorized error. We use standard HTTP Basic Authentication over HTTPS.

​
Using Your Credentials

For Basic Authentication with Bluerails:
  • The Username is your ORGANIZATION_ID.
  • The Password is your secret API_KEY.
You need to provide these credentials in the Authorization header for every API request. Constructing the Header:
  1. Form the string ORGANIZATION_ID:API_KEY (your Organization ID, followed by a colon, followed by your secret API key).
  2. Base64 encode this string.
  3. Prepend Basic (with a space) to the Base64 encoded string.
Authorization: Basic YOUR_BASE64_ENCODED_ORGID_APIKEY_STRING
Most HTTP clients and libraries have built-in support for Basic Authentication. You usually just need to provide the Organization ID as the username and the API key as the password.

​
API Key Types

You will have separate API keys (and potentially Organization IDs) for different environments:
  • Test Credentials: Used for development and testing in the sandbox environment. Test API keys typically start with blue_test_sk_....
  • Live Credentials: Used for production requests processing real transactions. Live API keys typically start with blue_live_sk_....
Ensure you use the correct Organization ID and API key corresponding to the environment you intend to interact with. Test credentials cannot be used for live transactions, and vice-versa.

​
Obtaining Your Credentials

You can find your Organization ID and generate/manage your API keys from the Bluerails Dashboard (replace with actual link if different) under the API settings or developer section.

​
Example Request (using cURL)

Here’s how you might make a request using curl, letting it handle the Basic Auth encoding: 
# Replace org_... and blue_live_sk... with your actual credentials
# The '-u' flag tells curl to use Basic Auth.
# Format is 'USERNAME:PASSWORD' which translates to 'ORGANIZATION_ID:API_KEY'
curl https://api.bluerails.com/v1/accounts \
-u "org_1234567890abcdef:sk_live_YOUR_SECRET_API_KEY"
Alternatively, manually encoding and setting the header:
  1. Get your Base64 encoded credentials: (Placeholder for command to generate base64 string from ORG_ID:API_KEY)
# Replace with your actual Organization ID and API Key
# The '-n' flag prevents echo from adding a newline
echo -n 'org_1234567890abcdef:sk_live_YOUR_SECRET_API_KEY' | base64
# Example Output: b3JnXzEyMzQ1Njc4OTBhYmNkZWY6c2tfbGl2ZV9ZT1VSX1NFQ1JFVF9BUElfS0VZ
  1. Use the encoded string in the Authorization header: (Placeholder for curl command using -H Authorization: Basic)
# Replace with the actual Base64 output from step 1
curl https://api.bluerails.com/v1/accounts \
-H "Authorization: Basic b3JnXzEyMzQ1Njc4OTBhYmNkZWY6c2tfbGl2ZV9ZT1VSX1NFQ1JFVF9BUElfS0VZ"
  • Keep your API keys confidential! Treat them like passwords. Your Organization ID is generally less sensitive, but the API key must be kept secret.
  • Never share your secret keys in publicly accessible areas like GitHub repositories, client-side code, or public forums.
  • Only grant access to API keys to those who need them.
  • Consider rotating your API keys periodically for enhanced security. You can manage key rotation in the Bluerails Dashboard.