Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ubik-agent.com/llms.txt

Use this file to discover all available pages before exploring further.

All requests to the UBIK API must be authenticated. This guide covers the available authentication methods and how to implement secure multi-tenancy for your users.

​
Authentication Methods

There are two primary ways to authenticate with the UBIK API, depending on your integration context:

​
1. API Key (Server-Side)

For backend-to-backend communication, use your secret API Key. Pass it in the X-API-KEY header. This grants full access to your account resources.
cURL
-H "X-API-KEY: YOUR_API_KEY"
Keep your API key secure as if it were a password and never expose it in client-side code (browsers, mobile apps).
You can optionally provide an external_user_id (in headers or body) when using the API Key. This allows you to perform actions on behalf of a specific end-user while using your server-side credentials.
cURL
-H "X-API-KEY: YOUR_API_KEY"
-H "external_user_id: user_123"

​
2. Scoped JWT (Client-Side & Multi-Tenant)

For frontend applications or when you need to isolate data for specific end-users, use a short-lived JSON Web Token (JWT).
  1. Generate Token: Call POST /auth/token from your backend using your API Key. You can optionally pass an external_user_id to scope the token to a specific user.
  2. Use Token: Pass the token in the Authorization header.
cURL
-H "Authorization: Bearer <ACCESS_TOKEN>"
This method is secure for public clients because the token is short-lived and can be restricted to specific user data.

​
Multi-Tenancy & Data Isolation

UBIK is designed to support multi-tenant applications out of the box. You can manage millions of your own end-users under a single UBIK account using the external_user_id parameter. When you authenticate a request with an external_user_id (either via a scoped JWT or by passing it in the request body/header), the API enforces a Hybrid Access Model:

​
1. Private Resources (Strict Isolation)

  • Agent Sessions and Tool Executions created with a specific external_user_id are strictly private. They can only be accessed by that same user ID.
  • User A cannot see User B’s chat history or tool results.

​
2. Shared Resources (Hybrid Access)

  • Workspaces and Documents follow a hybrid model. A user can access:
    • Private Resources: Created specifically for them (tagged with their external_user_id).
    • Global Resources: Created in your account without any external_user_id (e.g., shared project workspaces, knowledge bases).
  • This allows you to build agents that have access to both your company’s shared knowledge base and the user’s private context simultaneously.

​
Why use external_user_id?

  1. Automatic Filtering: The API automatically filters list endpoints based on the rules above. You don’t need to build complex filtering logic in your backend.
  2. Security Boundaries: It enforces strict isolation at the database level.
  3. Simplified Auth: You can generate short-lived, scoped tokens for your frontend clients that encode this ID.
Important: If you do not provide an external_user_id, the session or tool execution will have full access to all resources associated with your API Key. This effectively grants “Admin” privileges and should never be used for end-user facing integrations.

​
Integration Examples

​
Server-Side Integration (API Key)

If your backend server communicates with UBIK, you can simply pass the external_user_id in the request body while using your main API Key.
cURL
curl -X POST "https://app.ubik-agent.com/api/v1/agent-sessions" \
     -H "X-API-KEY: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "assistant_id": "asst_123...", 
           "external_user_id": "user_456",
           "title": "Customer Support Chat"
         }'

​
Client-Side Integration (Scoped JWT)

If you are integrating UBIK directly into a frontend application (like a chat widget), do not expose your API Key. Instead, generate a short-lived JWT token on your server that encodes the external_user_id. Step 1: Generate a Scoped Token (Server-Side) Call this endpoint from your backend to get a token for a specific user.
cURL
curl -X POST "https://app.ubik-agent.com/api/v1/auth/token" \
     -H "X-API-KEY: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "external_user_id": "user_456",
           "expires_in_minutes": 60
         }'
Step 2: Use the Token (Client-Side) Pass the returned access_token in the Authorization header. The external_user_id is automatically enforced, so you don’t need to send it in the body.
cURL
curl -X POST "https://app.ubik-agent.com/api/v1/agent-sessions" \
     -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
           "assistant_id": "asst_123...",
           "title": "Customer Support Chat"
         }'