Prisme.ai takes security seriously and provides multiple layers of protection for your data and API interactions. This guide covers security best practices, authentication mechanisms, and authorization models to help you build secure applications with the Prisme.ai API.

​
Authentication and Authorization

Prisme.ai offers several authentication methods:

JWT Authentication

  • Used for web applications
  • Session-based authentication
  • Handled by api-gateway service
  • Issued after OIDC authentication or anonymous login

Access Tokens

  • Long-lived authentication
  • Used for integrations and scripts
  • Can be generated by authenticated users
  • UUID-based opaque tokens

API Keys

  • Scoped to specific workspaces
  • Fine-grained permission control
  • Ideal for third-party integrations
  • Can be created with expiration dates
For detailed information on these authentication methods, try the Playground .

​
Network Security

1

TLS Encryption

All API communications should use TLS encryption (HTTPS):
  • Prisme.ai API endpoints only accept HTTPS connections
  • Self-hosted instances should be configured with valid TLS certificates
  • Minimum TLS version 1.2 is recommended
  • Client applications should validate server certificates
Never send sensitive data over unencrypted connections. Always verify you’re using https:// URLs for API calls.
2

Microservices Architecture

Prisme.ai uses a secure microservices architecture:
  • The api-gateway is the only publicly exposed service
  • Backend microservices are in a private network
  • Internal services trust the x-prismeai-user-id header from the api-gateway
  • Service-to-service communication uses internal authentication
3

IP Restrictions

For self-hosted deployments, consider implementing IP restrictions:
  • Limit API access to specific IP ranges
  • Use VPNs or private networks for sensitive operations
  • Configure firewalls to restrict access to the api-gateway
  • Implement network policies in Kubernetes deployments
# Example Kubernetes Network Policy
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: api-gateway-policy
  namespace: prisme-system
spec:
  podSelector:
    matchLabels:
      app: api-gateway
  ingress:
  - from:
    - ipBlock:
        cidr: 10.0.0.0/24
    ports:
    - protocol: TCP
      port: 443

​
Data Security

Data Encryption

  • All data in transit is encrypted using TLS
  • Sensitive data at rest is encrypted
  • Encryption keys are rotated regularly
  • JWT signing keys are automatically rotated

Secret Management

  • API keys and secrets are securely stored
  • Passwords are hashed with strong algorithms
  • Workspace secrets are encrypted at rest
  • Environment variables for sensitive configuration

Data Isolation

  • Multi-tenant architecture with data isolation
  • Workspace-level data segregation
  • Database-level access controls
  • Row-level security where appropriate

Audit Logging

  • Authentication events are logged
  • API access is recorded
  • Permission changes are tracked
  • Security-relevant actions are audited

​
JWT Security

​
Security Best Practices

1

Secure Token Handling

Handle authentication tokens securely:
  • Store tokens in secure HTTP-only cookies or secure storage
  • Never expose tokens in URLs or client-side code
  • Implement token refresh mechanisms
  • Set appropriate token expiration times
  • Revoke tokens when no longer needed
For web applications, consider using the authorization code flow with PKCE for enhanced security.
2

Implement Least Privilege

Follow the principle of least privilege:
  • Use API keys with minimal required permissions
  • Create role-specific tokens for different operations
  • Regularly audit and revoke unused access
  • Use workspace-scoped tokens instead of global ones
// Example of creating a minimally privileged API key
const response = await fetch('https://api.studio.prisme.ai/v2/workspaces/ws-123/apiKeys', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${userToken}`
  },
  body: JSON.stringify({
    name: 'Read-only Document Access',
    permissions: [
      {type: 'workspace', id: 'ws-123', action: 'read'},
      {type: 'document', id: '*', action: 'read'}
    ],
    expiresIn: 7 * 24 * 60 * 60 // 7 days
  })
});
3

Input Validation

Always validate input data:
  • Validate data types and formats
  • Sanitize inputs to prevent injection attacks
  • Use schema validation for request bodies
  • Implement proper error handling for invalid inputs
// Example of input validation
function validateWorkspaceId(workspaceId) {
  // Check for correct format (example: ws-123456)
  if (!/^ws-[a-zA-Z0-9]{6,}$/.test(workspaceId)) {
    throw new Error('Invalid workspace ID format');
  }
  return workspaceId;
}
4

Secure Automation Development

When developing automations and integrations:
  • Avoid storing sensitive data in automation code
  • Use workspace secrets for credentials and tokens
  • Implement proper error handling and logging
  • Validate outputs from untrusted sources
  • Limit HTTP request capabilities to necessary endpoints
# Example of using workspace secrets in automation
do:
  - fetch:
      method: POST
      url: ${secrets.API_ENDPOINT}
      headers:
        Authorization: Bearer ${secrets.API_TOKEN}
      body:
        data: ${input.data}
5

Regular Security Review

Implement a regular security review process:
  • Audit API keys and access tokens
  • Review user permissions and roles
  • Check for unused integrations
  • Monitor for suspicious activity
  • Update client libraries and dependencies

​
Self-Hosted Security Considerations

For self-hosted Prisme.ai deployments:

Kubernetes Security

  • Enable Pod Security Policies
  • Implement network policies
  • Use securityContext settings
  • Keep Kubernetes version updated

Container Security

  • Use minimal base images
  • Scan containers for vulnerabilities
  • Apply principle of least privilege
  • Don’t run containers as root

Secret Management

  • Use Kubernetes secrets or external vault
  • Implement secrets encryption at rest
  • Rotate secrets regularly
  • Limit secret access to necessary pods

Database Security

  • Enable authentication and encryption
  • Implement network isolation
  • Apply least privilege for database users
  • Regular backup and recovery testing

​
Security Monitoring and Incident Response

1

Security Monitoring

Implement monitoring for security events:
  • Authentication failures and successes
  • Permission changes
  • API key creation and usage
  • Rate limit violations
  • Unusual access patterns
For self-hosted deployments, integrate with your SIEM system for centralized monitoring.
2

Logging

Configure comprehensive logging:
# Example logging configuration
- emit:
   event: 
   payload: 
     level: info
     securityEvents: true
     accessLogs: true
     authenticationEvents: true
     format: json
     outputs:
       - type: stdout
       - type: elasticsearch
         config:
           url: https://elasticsearch:9200
           index: prisme-logs
Ensure logs don’t contain sensitive information like tokens, passwords, or personal data.
3

Incident Response

Prepare for security incidents:
  • Document incident response procedures
  • Define roles and responsibilities
  • Test response plans periodically
  • Establish communication channels
  • Implement post-incident reviews

​
Compliance and Auditing

Audit Logs

Prisme.ai maintains audit logs for compliance purposes:
  • User access and actions
  • Administrative changes
  • Authentication events
  • Data access patterns
Access audit logs through the API or admin console.

Compliance Support

Prisme.ai helps meet various compliance requirements:
  • Data residency options
  • Data retention controls
  • Access control documentation
  • Security assessment support

​
Next Steps

Authentication

Learn more about authentication methods

Rate Limits

Understand API usage limits

Versioning

Learn about API versioning strategy