Security

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

Authentication Methods
Authorization Model

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

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.

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

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

JWT Signing and Rotation

The api-gateway signs JWTs using JSON Web Keys (JWKs) that are automatically rotated:

JWKs are stored in the api-gateway database
Keys are rotated based on the JWKS_ROTATION_DAYS setting (default: 30 days)
When a JWK is rotated, it remains available for verifying existing JWTs
Rotated JWKs are removed after ACCESS_TOKENS_MAX_AGE (default: 30 days)
Key rotation happens during api-gateway startup

If a signing JWT has leaked, it must be manually deleted from the database before restarting the api-gateway and runtime services.

JWT Configuration

Environment variables for JWT configuration:

Variable	Description	Default Value
`JWKS_ROTATION_DAYS`	Rotation period in days	30
`JWKS_KTY`	JWK Algorithm family	RSA
`JWKS_ALG`	JWK signature algorithm	RS256
`JWKS_SIZE`	JWK size	2048
`ACCESS_TOKENS_MAX_AGE`	JWT expiration time in seconds	2592000 (30 days)

Public keys are available at https://api.studio.prisme.ai/oidc/jwks for JWT verification.

Security Best Practices

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.

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
  })
});

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;
}

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}

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

Infrastructure Security
Authentication Integration

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

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.

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.

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

Introduction

AI Builder Endpoints

Authentication and Authorization

JWT Authentication

Access Tokens

API Keys

Network Security

Data Security

Data Encryption

Secret Management

Data Isolation

Audit Logging

JWT Security

Security Best Practices

Self-Hosted Security Considerations

Kubernetes Security

Container Security

Secret Management

Database Security

Security Monitoring and Incident Response

Compliance and Auditing

Audit Logs

Compliance Support

Next Steps

Authentication

Rate Limits

Versioning

Introduction

AI Builder Endpoints

​Authentication and Authorization

JWT Authentication

Access Tokens

API Keys

​Network Security

​Data Security

Data Encryption

Secret Management

Data Isolation

Audit Logging

​JWT Security

​Security Best Practices

​Self-Hosted Security Considerations

Kubernetes Security

Container Security

Secret Management

Database Security

​Security Monitoring and Incident Response

​Compliance and Auditing

Audit Logs

Compliance Support

​Next Steps

Authentication

Rate Limits

Versioning

Authentication and Authorization

Network Security

Data Security

JWT Security

Security Best Practices

Self-Hosted Security Considerations

Security Monitoring and Incident Response

Compliance and Auditing

Next Steps