Authentication

All API requests require authentication via a Bearer token in the Authorization header.

Bearer Token

Include your API key in the Authorization header of every request.

curl https://samreshuuu.ru/api/v1/sessions \ -H "Authorization: Bearer sk-org-your_api_key"

Language Examples

import requests API_KEY = "sk-org-your_api_key" BASE_URL = "https://samreshuuu.ru/api/v1" headers = {"Authorization": f"Bearer {API_KEY}"} response = requests.get(f"{BASE_URL}/sessions", headers=headers)

Organization Context

If you belong to multiple organizations, pass the X-Org-Id header to select the context.

curl https://samreshuuu.ru/api/v1/sessions \ -H "Authorization: Bearer sk-org-your_api_key" \ -H "X-Org-Id: org_abc123"

Token Format

API keys are prefixed with sk-org-. The full secret is shown only once, at creation — store it securely. List and revoke endpoints only ever return the key prefix, never the secret.

Scopes

Every key carries a list of scopes, enforced per endpoint. If a key is missing the scope an endpoint requires, the request fails with 403 AUTH_PERMISSION_DENIED. A key with the admin scope bypasses every per-scope check. New keys default to write:tools when no scopes are specified.

Scope	Grants
`read:tools`	Read tool and connector metadata
`write:tools`	Execute tools and connectors
`read:data`	Read your organization's data
`chat`	Call the OpenAI-compatible `/v1/chat/completions` endpoint
`connector:gateway`	Direct connector gateway access
`admin`	Full access — bypasses per-scope checks

Managing API Keys

Keys are issued, listed, and revoked per organization. Each key expires after expires_in_days (default 90, range 1–365).

# Create a key — the full secret is returned once curl -X POST https://samreshuuu.ru/api/v1/organizations/$ORG_ID/api-keys \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "production", "scopes": ["chat", "write:tools"], "expires_in_days": 90}' # List keys — prefix, scopes, and last_used_at only curl https://samreshuuu.ru/api/v1/organizations/$ORG_ID/api-keys \ -H "Authorization: Bearer $ADMIN_TOKEN" # Revoke a key curl -X DELETE https://samreshuuu.ru/api/v1/organizations/$ORG_ID/api-keys/$KEY_ID \ -H "Authorization: Bearer $ADMIN_TOKEN"

Authentication Errors

An invalid or expired token results in a 401 response.

{ "detail": { "code": "AUTH_TOKEN_EXPIRED", "message": "The provided authentication token has expired.", "hint": "Generate a new API token in your dashboard." } }

FAQ

How do I authenticate a request?

Send your API key as a Bearer token in the Authorization header: Authorization: Bearer sk-org-your_api_key. Every API request requires it.

I belong to multiple organizations — how do I pick one?

Pass the X-Org-Id header (for example X-Org-Id: org_abc123) to select the organization context for the request.

What happens if my key lacks a required scope?

The request fails with 403 AUTH_PERMISSION_DENIED. Each endpoint enforces specific scopes; a key with the admin scope bypasses per-scope checks, and new keys default to write:tools.

Can I retrieve a key's secret after creating it?

No. The full secret is shown only once, at creation. List and revoke endpoints return only the key prefix, never the secret. Keys expire after expires_in_days (default 90, range 1–365).

Frequently asked questions

How do I authenticate a request?

Send your API key as a Bearer token in the Authorization header: Authorization: Bearer sk-org-your_api_key. Every API request requires it.

I belong to multiple organizations — how do I pick one?

Pass the X-Org-Id header (for example X-Org-Id: org_abc123) to select the organization context for the request.

What happens if my key lacks a required scope?

The request fails with 403 AUTH_PERMISSION_DENIED. Each endpoint enforces specific scopes; a key with the admin scope bypasses per-scope checks, and new keys default to write:tools.

Can I retrieve a key's secret after creating it?

No. The full secret is shown only once, at creation. List and revoke endpoints return only the key prefix, never the secret. Keys expire after expires_in_days (default 90, range 1–365).

Was this page helpful?