API keys
API keys authenticate your applications when using Superinterface's libraries and endpoints.
Use these REST endpoints to manage public API keys in a workspace or create keys across workspaces with an organization API key.
Note: A private workspace API key can create public API keys for its workspace. An organization API key can create public or private API keys for any workspace in the organization.
Endpoints
Manage your API keys with these REST endpoints.
List API keysRetrieve a list of public API keys
Create an API keyCreate a new API key
Get an API keyRetrieve a specific public API key
Update an API keyUpdate an existing public API key
Delete an API keyDelete an existing public API key
ApiKey type
ApiKeyType
Possible values for
ApiKeyType are:PUBLICPRIVATEPublic API keys are designed for use in frontend applications.
Private API keys have full access to your workspace and should only be used in secure server environments.
Example API key
const apiKey = {
id: '40cfe680-fee5-49b9-b386-6a7097eb8497',
type: 'PUBLIC',
name: 'Production website API key',
value: '77afd9c6-519f-4336-a39e-e739143f0a5c',
createdAt: '2024-01-15T10:30:00Z',
updatedAt: '2024-01-15T10:30:00Z',
}
API key types
Public API keys
Public API keys are designed to be used in frontend applications and have restricted permissions:
Safe for client-side use: Can be exposed in frontend code
Read-only access: Cannot modify workspace settings or sensitive data
Rate limited: Have usage limits to prevent abuse
Scoped access: Can only access interfaces and threads, not management functions
Usage example
import { SuperinterfaceProvider, Thread } from '@superinterface/react'
const App = () => (
<SuperinterfaceProvider
variables={{
publicApiKey: '1be04533-978e-4acb-8851-d45477e95a06',
}}
>
<Thread />
</SuperinterfaceProvider>
)
Private API keys
Private API keys have full access to your workspace and should never be exposed:
Server-side only: Never use in frontend applications
Full access: Can manage assistants, providers, and all workspace resources
Administrative access: Can perform all operations via REST API
Important: Private API keys should only be used in secure server environments and never exposed in client-side code. If you accidentally expose a private API key, immediately revoke it and generate a new one.
Organization API keys
Organization API keys let you manage workspaces and API keys across an organization:
Workspace management: Create and update workspaces in any organization
Key management: Create public or private API keys for any workspace
Requires an organization: Create an organization first, then generate keys in Organization settings → API keys
Important: Organization API keys cannot manage assistants or other workspace resources. Store them securely and rotate them if exposed.
Security best practices
For public API keys
Use in frontend applications: Safe to include in client-side code
Environment-specific keys: Create separate keys for development, staging, and production
Monitor usage: Keep track of which applications are using which keys
For private API keys
Server-side only: Never expose in client-side code or version control
Environment variables: Store in secure environment variables
Minimal exposure: Only use when server-to-server communication is required
For organization API keys
Server-side only: Never expose in client-side code or version control
Organization-wide impact: Compromise affects all workspaces
Rotate regularly: Revoke and regenerate keys if compromised or periodically
Error responses
All endpoints may return these common error responses:
401 Unauthorized
{
"error": "Unauthorized",
"message": "Invalid or missing API key"
}