OpenSERP Cloud authenticates every request with a bearer token — your API key secret. There are no per-user OAuth flows, no signed URLs, and no IP allow lists today.

Base URL

https://api.openserp.org

All Cloud endpoints live under /v1/.

The Authorization header

Pass your API key secret as a bearer token on every request:

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

A missing or invalid token returns 401 Unauthorized:

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

Key format

Cloud secrets always start with osk_live_ followed by a long random suffix. The dashboard also shows a short prefix (the first 8 characters after the underscore) — that prefix is safe to log for debugging, the full secret is not.

osk_live_a1b2c3d4...
         ^^^^^^^^  ← prefix shown in the dashboard
         full secret — keep this private

Creating and rotating keys

Manage keys at /dashboard/keys:

• Create — name the key (e.g. prod-worker, ci), copy the secret once. We never show the full secret again.
• Revoke — invalidates the key immediately. In-flight requests are rejected.
• Rotate — create a new key, deploy it, then revoke the old one. Cloud does not auto-expire keys.

A typical rotation looks like:

# 1. Create new key in the dashboard, copy the secret
# 2. Roll your secret store / .env
# 3. Verify traffic is using the new key (the prefix changes)
# 4. Revoke the old key in the dashboard

Verifying a key from code

The /v1/me endpoint returns the account associated with a secret. Useful for health checks at boot:

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

{ "email": "[email protected]", "credits_remaining": 4250 }

If the key is revoked or wrong, this call returns 401. The dashboard’s Search Playground uses this same endpoint to validate the secret you paste in.

Storing secrets safely

• Server-side only. Never ship osk_live_... to a browser, mobile app, or any client you don’t control.
• Environment variables or a secrets manager — not source control. The standard .gitignore for .env files applies.
• One key per environment / service — so a leak only forces one rotation, not a fleet-wide change.

If you suspect a key is compromised, revoke it from /dashboard/keys immediately. Charges stop the moment revocation completes.

Common 401 reasons

See Errors & rate limits for the full list of error codes.