Authentication

The GYBC platform supports three authentication methods.

JWT Authentication (Dashboard)

For dashboard users authenticated via Firebase. Tenant ID comes from the tenant_id custom claim. Pass the Firebase ID token as a Bearer token.

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/list-threads \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{}'

API Key Authentication (Backend-to-Backend)

For programmatic access from customer backends. Secret keys use the sk_* prefix and publishable keys use the pk_* prefix.

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/list-threads \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{}'

User Impersonation

API keys with the users:impersonate scope can act on behalf of specific users by setting the X-On-Behalf-Of header:

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/send-message \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{"conversation_key": "conv_abc", "user_message": {"role": "user", "content": "Hello"}}'

Publishable Key Authentication (Client Apps)

For end-user facing applications (iOS, web) in a multi-tenant setup. Requires both a publishable key (pk_*) and a user JWT. See Multi-Tenancy for the full setup guide.

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/list-threads \
  -H "X-API-Key: pk_your_key_here" \
  -H "Authorization: Bearer <firebase-user-jwt>" \
  -H "Content-Type: application/json" \
  -d '{}'

Tenant Requirement

JWT-authenticated users must have a tenant_id custom claim. Requests from JWT users without a tenant are rejected with 403 Forbidden — except /api/v1/orgs/create, which allows org-less JWTs for initial organization setup.

API key users are unaffected — the tenant is derived from the key's metadata.

See Multi-Tenancy for details on tenant isolation.

Rate Limit Headers

All API responses include rate limit information when using API key authentication:

Header	Description
X-RateLimit-Limit	Maximum requests in the current window
X-RateLimit-Remaining	Requests remaining
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds until next request allowed (on 429 responses)

See the API Key Guide for rate limit configuration.

Request Format

All API endpoints are accessed through the KrakenD API gateway using REST-style paths:

POST /api/v1/<domain>/<service>/<method>
Content-Type: application/json

Request and response bodies use protojson encoding (JSON representation of Protocol Buffer messages).

Code Examples

Python

import requests

BASE_URL = "https://api.yocaso.dev"
API_KEY = "sk_your_key_here"

headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json",
}

response = requests.post(
    f"{BASE_URL}/api/v1/llm/gateway/list-threads",
    headers=headers,
    json={},
)
print(response.json())

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://api.yocaso.dev/api/v1/llm/gateway/list-threads"
    body, _ := json.Marshal(map[string]any{})

    req, _ := http.NewRequest("POST", url, bytes.NewReader(body))
    req.Header.Set("X-API-Key", "sk_your_key_here")
    req.Header.Set("Content-Type", "application/json")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    fmt.Println("Status:", resp.Status)
}

Node.js

const response = await fetch(
  "https://api.yocaso.dev/api/v1/llm/gateway/list-threads",
  {
    method: "POST",
    headers: {
      "X-API-Key": "sk_your_key_here",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}),
  }
);
const data = await response.json();
console.log(data);