#Authentication

All API requests require authentication. The Creatoria Agent API uses API Keys for identity verification.

#API Key Authentication

Include the API Key in the header of each request:

X-API-Key: sk_your_api_key_here

#Example

bashcurl -X GET "https://your-domain.com/v1/agents" \
  -H "X-API-Key: sk_your_api_key_here"

#Project Context

Some operations (such as creating an Agent) require a Project context. Pass it via the X-Project-Id request header:

X-Project-Id: proj_abc123

If the API Key is already bound to a Project, this header is not required. However, if the API Key is not bound to a Project, operations like creating an Agent require explicitly specifying one.

#Permissions and Roles

API Key permissions are controlled via the permissions field, which maps to the following roles:

API Key Permission	Mapped Role	Allowed Operations
`admin`	admin	All operations (GET, POST, PATCH, PUT, DELETE)
`write`	member	Read and write operations (GET, POST, PATCH)
`read`	viewer	Read-only operations (GET)

#Permission Check Rules

Each endpoint declares its required permissions, for example:

Permission Identifier	Description
`agents:create`	Create Agent
`agents:update`	Update Agent
`agents:delete`	Delete Agent
`agent:chat`	Chat with Agent
`session:create`	Create session
`session:read`	View session
`session:update`	Update session
`session:delete`	Delete session
`messages:read`	View message history
`kb:read`	View knowledge base
`kb:create`	Create knowledge base
`kb:write`	Update knowledge base
`kb:delete`	Delete knowledge base
`kb:upload`	Upload document
`rag:search`	Search knowledge base
`tools:create`	Create tool configuration
`tools:update`	Update tool configuration
`tools:delete`	Delete tool configuration
`webhooks:create`	Create Webhook
`webhooks:read`	View Webhook
`webhooks:update`	Update Webhook
`webhooks:delete`	Delete Webhook

#Multi-Tenant Architecture

Creatoria uses a three-level tenant architecture:

Organization
  └── Project
       └── Agent

Organization: The top-level isolation unit with independent resources and quotas
Project: Project-level isolation for managing different business scenarios
Agent: The smallest resource unit, belonging to a specific Project

API Keys are associated with an Organization at creation time and can optionally be bound to a specific Project.

#Security Recommendations

Do not expose API Keys in frontend code -- only use them in backend servers
Use different API Keys for different environments (development, testing, production)
Rotate API Keys regularly and delete keys that are no longer in use
Follow the principle of least privilege: only grant API Keys the permissions they actually need