Authenticate with the Alphacast API

Learn how to authenticate Alphacast API requests using your API key via HTTP Basic Auth or as a query parameter, with examples in curl and Python.

Every request to the Alphacast API must include an API key. You can obtain your key from your account settings at alphacast.io — navigate to Account Settings → API Key to generate or view your key. Alphacast supports two ways to pass your API key: as an HTTP Basic Auth credential, or as a URL query parameter.

Your API key grants full access to your Alphacast account. Do not share it publicly, commit it to version control, or expose it in client-side code.

Authentication methods

Alphacast supports two ways to pass your API key. HTTP Basic Auth is the recommended option for most integrations.

HTTP Basic Auth (recommended)

Pass your API key as the username with an empty password. Credentials travel in the Authorization header, never in the URL.

curl

curl https://api.alphacast.io/datasets \
  -u YOUR_API_KEY:

import requests

response = requests.get(
    "https://api.alphacast.io/datasets",
    auth=("YOUR_API_KEY", "")
)
print(response.json())

const response = await fetch("https://api.alphacast.io/datasets", {
  headers: { Authorization: "Basic " + btoa("YOUR_API_KEY:") },
});
const datasets = await response.json();

The colon after the API key (in curl) and the empty string as the second element of the auth tuple (in Python) indicate an empty password. Most HTTP clients accept this convention without additional configuration.

Query parameter

Append ?apiKey=YOUR_API_KEY to any request URL. Convenient for quick tests in a browser or when your HTTP client does not easily support Basic Auth headers.

curl

curl "https://api.alphacast.io/datasets?apiKey=YOUR_API_KEY"

import requests

response = requests.get(
    "https://api.alphacast.io/datasets",
    params={"apiKey": "YOUR_API_KEY"}
)
print(response.json())

const url = new URL("https://api.alphacast.io/datasets");
url.searchParams.set("apiKey", "YOUR_API_KEY");
const response = await fetch(url);
const datasets = await response.json();

When using the query parameter method, make sure your API key is not captured in server logs or browser history, especially in production environments. HTTP Basic Auth is generally more secure because credentials travel in headers, not in the URL.

Authentication errors

If a request is missing credentials or the API key is invalid, the API responds with HTTP 401 Unauthorized:

{"error": "Unauthorized"}

Common causes:

• The API key was not included in the request
• The API key has been revoked or regenerated
• The key was passed as the password instead of the username in Basic Auth

Keeping your API key safe

Store your API key in an environment variable rather than hardcoding it. For example, set ALPHACAST_API_KEY in your environment and read it at runtime:

import os
import requests

api_key = os.environ["ALPHACAST_API_KEY"]

response = requests.get(
    "https://api.alphacast.io/datasets",
    auth=(api_key, "")
)

If you believe your API key has been compromised, regenerate it immediately from your account settings at alphacast.io. Regenerating a key immediately invalidates the previous one.