OpenSERP Cloud uses API-key bearer authentication. Create a key in the dashboard, store the secret server-side, and send it on every request.

Base URL

https://api.openserp.org

All Cloud paths use the /v1/ prefix (for example /v1/google/search).

With the JavaScript SDK

The SDK fills in the base URL and Authorization header for you. Set apiKey once on the client:

import { OpenSERP } from "@openserp/sdk";

const client = new OpenSERP({ apiKey: process.env.OPENSERP_KEY });

const account = await client.me();
console.log(account.email, account.credits_remaining);

With the Python SDK

import os
from openserp import OpenSERP

client = OpenSERP(api_key=os.environ["OPENSERP_KEY"])

account = client.me()
print(account.email, account.credits_remaining)

With raw HTTP

Send the secret as a bearer token:

GET /v1/google/search?text=openserp HTTP/1.1
Host: api.openserp.org
Authorization: Bearer osk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

A missing, invalid, or revoked key returns 401 Unauthorized:

{
  "error": "unauthorized",
  "code": 401,
  "message": "missing or invalid API key"
}

Key format

Cloud secrets start with osk_live_ followed by a random suffix. The dashboard also shows a short prefix so you can identify keys in logs and support tickets without exposing the full secret:

osk_live_a1b2c3d4...
         ^^^^^^^^  safe to log

Log the prefix when you need to debug which key was used. Never log the full secret.

Validate a key

/v1/me returns the account associated with the key and the live credit balance. It’s free to call and useful as a startup probe or deployment smoke test:

const account = await client.me();
console.log(account.credits_remaining);

curl https://api.openserp.org/v1/me \
  -H "Authorization: Bearer $OPENSERP_KEY"

{ "email": "you@example.com", "credits_remaining": 4250 }

Create and rotate keys

Manage keys in API keys:

A safe rotation flow:

1. Create a new key in the dashboard and copy the secret.
2. Update OPENSERP_KEY in your secret store.
3. Deploy and confirm requests succeed with the new key (client.me() works well).
4. Revoke the old key in the dashboard.

This way no in-flight requests fail during the swap.

Store secrets safely

• Keep API keys server-side. Do not ship osk_live_... in browser code, mobile apps, public repos, logs, or analytics events.
• Use environment variables or a secrets manager.
• Use separate keys per environment (local, staging, production, CI). Revoking one then never affects another.
• Revoke unused keys so retired deployments cannot keep sending traffic.

If a key may be compromised, revoke it immediately in API keys and deploy a new one.

Common 401 fixes

See Errors & rate limits for the full error reference.