Authenticating and getting a token

The Python example below demonstrates how to obtain an access token for using the API. While the example is written in Python, the same process applies to any programming language. Once you have your access token, you can use it to submit and solve optimization models, download results, and perform other API operations.

The full API docs can be found here.

Prerequisites

1. Your API key ID and secret, which the sample script reads from environment variables
2. Your organization ID, available on the API keys settings page

To interact with the Rose API, you must first authenticate using your API signature. This will return an access token that is valid for 24 hours. Save the token and its expiration timestamp locally—ideally in a JSON file—so that your application can reuse it until it expires. That way you do not request a new token for every API call. You only need to request a token once every 24 hours.

First-time authentication

To authenticate for the first time:

1. Generate your API signature
   See How to generate your API signature for detailed instructions
2. Send the signature to the authentication endpoint
3. Receive a response containing:
   • An access_token (used for all API requests)
   • An expires_in field (number of seconds the token is valid—typically 86,400 for 24 hours)

Recommended token storage

We recommend saving the following fields to a local JSON file in a format like this:

{
  "access_token": "your_token_here",
  "expires_at": "2038-01-01T03:14:15.926536"
}

This approach avoids unnecessary token requests and streamlines your integration with the Rose API.

Complete example

Below is a complete example that returns the token you need to pass in the header on subsequent calls to the API. If you already have a valid token saved, it will reuse that one. Otherwise it will generate and save a new token.

import datetime
import hashlib
import hmac
import json
import os
import requests

from datetime import datetime, UTC, timedelta

# === USER INPUTS ===
API_KEY_ID = os.getenv("API_KEY_ID")
API_KEY_SECRET = os.getenv("API_KEY_SECRET")
ORGANIZATION_ID = os.getenv("ORGANIZATION_ID")
TOKEN_CACHE_FILE = ".simplerose_token_cache.json"

BASE_URL = "https://sapi.prod.solaas.simplerose.com/api/1.0"


# === AUTHORIZATION FUNCTIONS ===
def generate_signature(api_key_id, api_key_secret, organization_id):
    if not api_key_id or not api_key_secret or not organization_id:
        raise EnvironmentError("Missing API_KEY_ID, API_KEY_SECRET, or ORGANIZATION_ID environment variable.")

    utc_date = datetime.now(UTC).strftime("%Y-%m-%d")
    message = f"{organization_id}:{utc_date}:{api_key_id}"
    return hmac.new(api_key_secret.encode(), message.encode(), hashlib.sha256).hexdigest()


# Save the access token and its expiration to disk
def save_token(auth_token):
    with open(TOKEN_CACHE_FILE, "w") as f:
        expires = (datetime.now() + timedelta(seconds=auth_token["expires_in"])).isoformat()
        json.dump({
            "access_token": auth_token["access_token"],
            "expires": expires
        }, f)


# Use the existing token on disk if it exists and has not expired
def load_token():
    if not os.path.exists(TOKEN_CACHE_FILE):
        return None
    with open(TOKEN_CACHE_FILE, "r") as f:
        data = json.load(f)
    if datetime.now() > datetime.fromisoformat(data["expires"]):
        return None
    return data["access_token"]


# Request a new authorization token
def authenticate():
    signature = generate_signature(API_KEY_ID, API_KEY_SECRET, ORGANIZATION_ID)
    payload = {"api_key_id": API_KEY_ID, "signature": signature}
    response = requests.post(f"{BASE_URL}/authenticate", json=payload)
    response.raise_for_status()
    auth_token = response.json()
    save_token(auth_token)
    return auth_token["access_token"]


# === EXAMPLE USAGE ===
if __name__ == "__main__":
    token = load_token() or authenticate()
    print(f"Access Token: {token}")