Skip to main content

API Authentication Guide

Authenticate with the Carbon Arc API using the carbonarc Python client.

Context​

Before you can fetch data or explore Carbon Arc’s insights and ontology, you’ll need to authenticate securely using an API token. This guide walks through setting up authentication using environment variables and initializing the API client.

Carbon Arc uses a token-based authentication model. You retrieve your token from the Carbon Arc Platform and use it to initialize your session via the carbonarc SDK.

API Authentication Step by Step​

This notebook covers secure handling and loading of your API authentication token.

1. Install Dependencies​

Ensure you have python-dotenv installed to load environment variables securely.

pip install python-dotenv

2. Create Your .env File​

In your project root, create a file named .env with the following content:

API_AUTH_TOKEN=your_api_key_here

3. Load and Validate the Token​

Use dotenv to load the token and verify it's present.

from dotenv import load_dotenv
import os

# Load variables from .env
load_dotenv()

# Retrieve the token
API_AUTH_TOKEN = os.getenv('API_AUTH_TOKEN')

# Validate presence
if not API_AUTH_TOKEN:
    raise RuntimeError("❌ API_AUTH_TOKEN is missing. Please add it to your .env file.")
print("✅ API_AUTH_TOKEN loaded successfully.")

4. Fallback Prompt (Optional)​

If you prefer not to store the token in a file, you can prompt for it at runtime:

import getpass

if not API_AUTH_TOKEN:
    API_AUTH_TOKEN = getpass.getpass("Enter your Carbon Arc API token: ")
    if not API_AUTH_TOKEN:
        raise RuntimeError("❌ No token provided.")
print("✅ API_AUTH_TOKEN obtained via prompt.")

5. Instantiate the Client with Your Token​

Now that you have a valid token, create the SDK client:

from carbonarc import CarbonArcClient

# Initialize the client
client = CarbonArcClient(api_token=API_AUTH_TOKEN)
print("✅ Carbon Arc client initialized with authenticated session.")

Next Steps​

  • Use the authenticated client to make API calls.
  • Store your token securely (e.g., CI secrets) when running in production.