Authentication and keys

Two key typesCopy Anchor Link

Create, edit and revoke keys under Metin asistanı → API anahtarları (Text assistant → API keys) in Sonecentral. Only workspace administrators see this section. A workspace can have up to 50 active keys; revoked keys do not count.

Send the keyCopy Anchor Link

Use the Authorization header:

Authorization: Bearer sk-sone-v1-...

x-api-key is also accepted. If both are supplied, Authorization takes precedence.

x-api-key: sk-sone-v1-...

OpenAI SDKs and Vercel AI SDK send their apiKey option as Authorization: Bearer automatically.

When the key is shownCopy Anchor Link

The complete key is shown once, at creation. Sonecentral stores only its hash. The list displays its prefix and final four characters. Request logs do not retain the key, whether sent through Authorization or x-api-key. If lost, create a new key and revoke the old one.

Rotate a keyCopy Anchor Link

Open Text assistant → API keys as a workspace administrator. Create a replacement with the required assistant scope, allowed origins and request permission. Copy it once, update your integration and verify it with GET /key, then revoke the old key. Rotation uses create-and-revoke; there is no separate rotate button. If a key is exposed, revoke it immediately.

Key-management responses use Cache-Control: no-store. Requests carrying Origin: null (for example from an opaque or sandboxed browser context) are refused; server requests omit Origin.

Key settingsCopy Anchor Link

• Name. Up to 80 characters to identify the key. Also returned by GET /key; do not include secrets.
• Type. Server or publishable. Cannot be changed after creation.
• Assistants. Which assistants the key can call. Selecting all includes every published workspace assistant, including future ones. You can select an unpublished assistant; the key starts working with it once published.
• Allowed origins. Publishable keys only, from 1 to 20 origins.
• Can receive order and appointment requests. Enabled by default. The assistant can create requests awaiting your team's approval. When disabled, it passes the details to your team instead. See Orders, appointments and privacy.

All settings except type can be edited later. Changes apply on the next request.

Allowed originsCopy Anchor Link

Browsers send Origin automatically on cross-origin requests. A publishable key is accepted only when Origin matches its allowlist. It cannot be used without an Origin header.

• Use a scheme and hostname, such as https://www.example.com. The hostname must contain at least one dot. For a non-443 port, use https://www.example.com:8443.
• Paths, query strings, * wildcards, IP addresses and https://localhost are not accepted.
• https://example.com and https://www.example.com are separate origins. Add both if needed.
• For development, only http://localhost and http://127.0.0.1 are allowed over HTTP, with or without a port, such as http://localhost:3000 or http://127.0.0.1:5173.

Hostnames are compared in lowercase. An origin outside the allowlist returns 403 origin_not_allowed.

Server keys do not belong in browsersCopy Anchor Link

Anyone can read a key embedded in website code and make requests on your behalf. Sonecentral rejects server-key requests carrying an origin not listed on that key with 403 secret_key_in_browser. The dashboard does not add origins to server keys, so browser-origin requests are rejected. Always use a publishable key in browsers.

This check is a safety net. Pages opened from a local file or a sandboxed frame can send Origin: null; Sonecentral rejects these requests too. A client outside the browser can omit or forge Origin, so this check does not protect an exposed key. Never include a server key in a browser, mobile app bundle or public repository.

Browser code can read these response headers: x-request-id, retry-after, x-should-retry and x-sone-conversation-id.

Developer contextCopy Anchor Link

With a server key, system and developer messages, Responses instructions, and Vercel AI SDK context are passed to the assistant as information only. For example, identify the product page the visitor is viewing or their app language preference.

This text cannot override business instructions or rules; instructions embedded in it are not followed. Multiple contexts are joined and limited to 2,000 characters. Responses rejects instructions above 2,000 characters or 4 KB of JSON with 400 instructions_too_long. Context applies only to the current turn; send it again if needed on the next request.

Context sent with a publishable key is ignored and not stored, because visitors can change it.

RevocationCopy Anchor Link

Revoking a key in API anahtarları disables it immediately. Subsequent requests return 401 revoked_api_key. Revocation cannot be undone and revoked keys cannot be edited. Existing conversations remain in Messages.

Stored responses created by a revoked key expire after 30 days. A new key that can call the same assistant can read them and continue with previous_response_id, but cannot delete them or see instructions, safety_identifier or user. See Stored responses.

Inspect the keyCopy Anchor Link

GET /key returns the current key's summary. Use it to check the workspace and available assistants during setup.

curl https://pb.sonecentral.com/api/v1/key \
  -H "Authorization: Bearer $SONE_API_KEY"

{
  "data": {
    "label": "pk-sone-v1-Ab3…",
    "name": "Web sitesi sohbeti",
    "kind": "publishable",
    "assistants": ["k3m9x2p7q1w8e4r"],
    "requests": true,
    "allowed_origins": ["https://www.ornek.com"],
    "limits": {
      "requests_per_minute_per_visitor": 30,
      "requests_per_hour": 1200,
      "read_requests_per_hour": 20000,
      "assistant_turns_per_hour": 60,
      "assistant_turns_per_day": 300,
      "browser_assistant_turns_per_hour": 40,
      "browser_assistant_turns_per_day": 200
    }
  }
}

Server-key limits:

{ "requests_per_minute": 120, "assistant_turns_per_hour": 60, "assistant_turns_per_day": 300 }

GET /key is a read and counts toward the key's limits.

ErrorsCopy Anchor Link

All codes: Errors.