Skip to main content

API Authentication

API Authentication Guide​

Authenticate with the Carbon Arc API using the official carbonarc Python SDK.

Context​

Carbon Arc uses token-based authentication. You must include your personal API token when initializing the SDK. This token can be securely managed using a .env file or entered at runtime.

Your API token is available from your Carbon Arc profile:
https://platform.carbonarc.co/profile

Step-by-Step Setup​

1. Install Dependencies​

Install the SDK and dotenv for environment variable management:

pip install --upgrade carbonarc
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.

import os
from dotenv import load_dotenv

load_dotenv()

API_AUTH_TOKEN = os.getenv("API_AUTH_TOKEN")

if not API_AUTH_TOKEN:
    raise RuntimeError("API_AUTH_TOKEN is missing. Please add it to your .env file.")
print("API 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.")

5. Initialize the Client with Your Token​

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

from carbonarc import CarbonArcClient

ca = CarbonArcClient(token=API_AUTH_TOKEN)
print("Carbon Arc client initialized.")

Next Steps​

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