User attributes

User attributes are key-value pairs attached to principals that provide dynamic context for security policies. They enable per-user data filtering without creating separate roles for each user.

Concepts

User attributes have three components:

Attribute key: The identifier for an attribute (like tenant_id or region). Keys must be defined in your organization before they can be used on principals.
Attribute value: The actual value attached to a principal for a given key. Values can be strings, numbers, or booleans.
Principals: Entities that can have attributes: embedded users, embedded organizations, API keys, and platform users.

How user attributes work

Attributes flow from configuration to query-time resolution in five steps:

Define attribute keys: Create attributes in your organization to establish which keys are valid.
Set values on principals: Attach attribute values to users via session tokens, the API, or the Console.
Configure roles: Specify which attributes are required or fixed on each role.
Resolve at request time: When a principal makes a request, Reeflow resolves their effective attributes:
- Start with the principal’s attributes (from session token or stored configuration)
- Apply fixed attributes from each assumable role, which override the principal’s values
- If multiple roles define the same fixed attribute, the last role processed wins
Apply in policies: Security policies reference resolved values via RF_USER_ATTR() to filter data dynamically.

Example: fixed attributes override principal values

A role grants query access to the reports table with a fixed attribute region = 'us' and a row filter region = RF_USER_ATTR('region').

The principal provides region = 'eu' in their session token:

Role resolved: The role applies (no required attributes).
Attributes resolved: region = 'us' (fixed value overrides the principal’s 'eu').
Result: Queries filter to region = 'us'. The principal cannot access EU data by passing a different value.

Setting attributes on principals

You can set attributes on principals in three ways, depending on the principal type and when the context is known.

Session tokens (embedded users)

Pass attributes when creating a session token. This allows your backend to set context dynamically per session:

TypeScript

const API_KEY_ID = 'key_abc123xyz';
const API_KEY_SECRET = 'your-api-key-secret';

const credentials = Buffer.from(`${API_KEY_ID}:${API_KEY_SECRET}`).toString('base64');
const response = await fetch('https://api.reeflow.io/embed/sessions', {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    embedded_user: {
      external_user_id: 'user-123',
      attributes: {
        tenant_id: 'acme',
        region: 'us-east-1',
      },
    },
  }),
});

const { token } = await response.json();

This is the most common approach for embedded analytics, where attribute values come from your application’s authentication.

Embedded users and organizations

Embedded users and organizations can have attributes set via direct assignment in the Console or via the API.

Platform users

Platform users (team members who sign in to the Console) can have attributes set via direct assignment in the Console or via the API.

Using attributes in security policies

Row-level security filters can reference user attributes to dynamically restrict data access. Instead of hardcoding filter values, you use the RF_USER_ATTR() function to resolve attribute values at query time.

The function takes an attribute key and returns the principal’s value for that attribute:

column_name = RF_USER_ATTR('attribute_key')

For example, in a multi-tenant application where each user has a tenant_id attribute:

tenant_id = RF_USER_ATTR('tenant_id')

This filter ensures each user only sees rows matching their tenant. The value is resolved from the principal’s attributes when the query executes.

For detailed usage and examples, see Row-level security.

Configuring attributes

Create attribute keys in the Console

Create the attribute keys that principals can use. Once created, you can assign values to these keys on embedded users, organizations, API keys, and platform users.

Navigate to Attributes in the main navigation, then click New Attribute to open the form.

Validation and constraints

Reeflow enforces the following constraints on attributes:

Constraint	Limit
Attributes per principal	10
Key length	64 characters
Key characters	Letters, numbers, hyphens, underscores, colons, dots
String value length	64 characters
Value types	String, number, or boolean

Attribute keys must be defined in the organization before use. Attempting to set an undefined attribute key returns an error.

Error handling

Scenario	Result
Attribute key not defined in organization	`400 Bad Request` with error listing invalid keys
`RF_USER_ATTR()` references missing attribute	`400 Bad Request` with “Attribute ‘name’ not found in context”
Required attribute missing from principal	Role is not assumed; may result in `403 Forbidden` if no other roles apply