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, which the sample script reads from environment variables

To interact with the Rose API, you must first authenticate using your API key. This will return an access token that is valid for 30 minutes. 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 30 minutes.

First-time authentication

To authenticate for the first time:

1. Send your API key to the authentication endpoint
2. Receive a JSON response containing:
   • An access_token (used for all API requests)
   • An expires_in field (number of seconds the token is valid for, will be 1800 for 30 minutes)

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 json
import os
import requests

from datetime import datetime, timedelta, UTC

# === USER INPUTS ===
ROSEPY_API_KEY_TOKEN = os.getenv("ROSEPY_API_KEY_TOKEN")
TOKEN_CACHE_FILE = ".simplerose_token_cache.json"

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


# === AUTHORIZATION FUNCTIONS ===
# 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(UTC) + 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(UTC) > datetime.fromisoformat(data["expires"]):
        return None
    return data["access_token"]


# Request a new authorization token
def authenticate():
    payload = {"api_key_token": ROSEPY_API_KEY_TOKEN}
    response = requests.post(
        f"{BASE_URL}/authenticate",
        json=payload,
        timeout=10)
    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}")