• Set up API access for the first time
• Log in with email and password to get an access token
• Refresh an expired access token using a refresh token
• Exchange an authorization code for tokens (browser SSO flow)
• Create, list, or revoke API keys

1. Create a Spuree account at studio.spuree.com
2. Go to studio.spuree.com/api-keys and create a key. Save it immediately — the key is only shown once.
3. Set the environment variable:
   bash

   export SPUREE_API_KEY="<your-api-key>"

1. Log in with

   POST /auth/token

   to get a temporary JWT
2. Create an API key with

   POST /v1/api-keys

3. Store the key in

   $SPUREE_API_KEY

1. Start a local HTTP server on an ephemeral port (49152–65535) to receive the callback.
2. Open the user's browser to the Spuree sign-in page with

   source=api

   and the port:

   https://studio.spuree.com/auth/signin?source=api&port=<port>

   The user logs in via Google SSO (or email/password) in the browser.
3. After login, Spuree redirects to

   http://localhost:<port>/callback?token=<exchange-code>

   . The agent receives the exchange code from this callback (valid for 60 seconds).
4. Exchange the code for a JWT:
   bash

   curl -X POST "https://studio.spuree.com/api/auth/token/exchange" \
     -H "Content-Type: application/json" \
     -d '{"code": "<exchange-code>"}'

5. Create an API key with the JWT (

   POST /v1/api-keys

   ) and store it in

   $SPUREE_API_KEY

   .

$SPUREE_API_KEY

X-API-Key: $SPUREE_API_KEY

"List my Spuree projects"

"Upload this file to my Spuree project"

refresh_token

curl -X POST "https://studio.spuree.com/api/auth/token/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "a1b2c3d4e5f6..."
  }'

• Each refresh token can only be used once. After refresh, use the new

  refresh_token

  for subsequent refreshes.
• If a refresh token is reused (already revoked), it returns 401.

studio.spuree.com/auth/signin?source=api

code

curl -X POST "https://studio.spuree.com/api/auth/token/exchange" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "exchange-code-here"
  }'

• Exchange codes expire after 60 seconds.
• Each code can only be used once.

name

scopes

{ "organizations": ["orgId1", ...] }

expiresAt

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "CI Pipeline Key",
  "key": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
  "createdAt": "2024-01-15T10:00:00Z",
  "expiresAt": null,
  "lastUsedAt": null,
  "scopes": { "organizations": ["64a7b8c9d1e2f3a4b5c6d7f0"] },
  "status": "active"
}

Important: The

key

field is only returned once at creation. Store it securely.

curl -X POST "https://data.spuree.com/api/v1/api-keys" \
  -H "Authorization: Bearer $SPUREE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI Pipeline Key",
    "scopes": { "organizations": ["64a7b8c9d1e2f3a4b5c6d7f0"] }
  }'

1. Obtain tokens with email and password:

   POST /auth/token → { access_token, refresh_token, expires_in, user }

2. Use access token for V1 API calls:

   Authorization: Bearer {access_token}

3. Refresh before the token expires (every ~55 minutes):

   POST /auth/token/refresh → { access_token, refresh_token, ... }

• expires_in

  is

  3600

  (1 hour). Refresh proactively at ~55 minutes to avoid failed requests.
• Always store and use the latest

  refresh_token

  — old ones are revoked after use.
• If refresh fails with 401, the user must log in again with email/password.

1. Log in to get a JWT
2. Create an API key scoped to the needed organizations:

   POST /v1/api-keys → { key: "a1b2c3d4..." }

3. Use the API key for all subsequent requests:

   X-API-Key: a1b2c3d4...

expiresAt