Security

Security best practices and authorization model for the Prisme.ai API

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

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 .

Authorization Model

Prisme.ai implements a flexible permission system:

Defining Roles

The RBAC system consists of several key elements:

• Roles: Sets of permissions that can be assigned to users
• Subjects: Resources that can be acted upon (pages, files, events, etc.)
• Actions: Operations that can be performed on subjects (read, create, update, etc.)
• Rules: Define which roles can perform which actions on which subjects
• Conditions: Optional criteria that further restrict when rules apply

Defining Roles

authorizations:
  roles:
    editor: {}  # Built-in role
    
    # Custom role for regular users
    user:
      auth:
        prismeai: {}  # Automatically assigned to all Prisme.ai users
        
    # Role for API access
    workspace:
      auth:
        apiKey: {}  # Can be used with API keys

Creating Rules

Define what each role can do with specific rules:

rules:
  # Allow editors to read and update workspaces
  - role: editor
    action:
      - read
      - get_usage
      - aggregate_search
      - update
    subject: workspaces
    
  # Give editors full control over files
  - role: editor
    action: manage  # Shorthand for all permissions
    subject: files

Each rule must include at least:

• action: What can be done (a single action or list)
• subject: What it can be done to (a single subject or list)

Rules can optionally specify:

• role: Which role this applies to (if omitted, applies to everyone)
• conditions: Restrict the rule to specific cases
• inverted: Set to true to make this a deny rule instead of allow
• reason: Documentation string for the rule

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

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

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

Infrastructure Security

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

Authentication Integration

Options for integrating with enterprise authentication:

OIDC Integration

Connect Prisme.ai to your OIDC provider:

• Configure OIDC client settings
• Map identity provider groups to roles
• Enable single sign-on

SAML Integration

Connect to enterprise SAML providers:

• Configure SAML service provider settings
• Set up attribute mapping
• Implement JIT provisioning

Example OIDC configuration:

providers:
  <ProviderName>:
    type: oidc
    config:
      client_id: "your client id"
      client_secret: "your client secret"
      authorization_endpoint: "idp authorization_endpoint"
      token_endpoint: "idp token_endpoint"
      jwks_uri: "idp public certificates endpoint"
      scopes: "openid email profile"

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