Worker RBAC

This guide walks you through enabling RBAC on your iii instance using the iii-worker-manager. Workers connect via WebSocket to a dedicated RBAC port, separate from the internal engine bridge.

1. Add RBAC Config to the Worker Manager

Add an iii-worker-manager entry with RBAC config to your engine config file. At minimum you need a port and an expose_functions list inside rbac:

iii-config.yaml

workers:
  # ... your existing workers ...

  - name: iii-worker-manager
    config:
      port: 49135
      rbac:
        expose_functions:
          - match("api::*")

This exposes all functions whose ID starts with api:: on port 49135 with no authentication.

2. Write an Auth Function

For production, authenticate workers by registering a function that validates credentials from the WebSocket upgrade request. The function receives an AuthInput and must return an AuthResult.

Node / TypeScript
Python
Rust

import type { AuthInput, AuthResult } from 'iii-sdk'
import { registerWorker } from 'iii-sdk'

const iii = registerWorker('ws://localhost:49134')

iii.registerFunction(
  'my-project::auth-function',
  async (input: AuthInput): Promise<AuthResult> => {
    const token = input.headers?.['authorization']?.replace(/^Bearer\s+/i, '')
    const apiKey = input.query_params?.['api_key']?.[0]

    if (!token && !apiKey) {
      throw new Error('Missing credentials')
    }

    const user = await validateCredentials(token || apiKey)

    return {
      allowed_functions: [],
      forbidden_functions: user.role === 'readonly'
        ? ['api::users::delete', 'api::users::update']
        : [],
      allowed_trigger_types: user.role === 'admin'
        ? ['cron', 'webhook']
        : undefined,
      allow_trigger_type_registration: user.role === 'admin',
      context: {
        user_id: user.id,
        role: user.role,
      },
    }
  },
)

from iii import AuthInput, AuthResult, register_worker

iii = register_worker('ws://localhost:49134')

async def auth_function(data: dict) -> dict:
    auth_input = AuthInput(**data)

    token = auth_input.headers.get('authorization', '').replace('Bearer ', '', 1)
    api_key = (auth_input.query_params.get('api_key') or [None])[0]

    if not token and not api_key:
        raise Exception('Missing credentials')

    user = await validate_credentials(token or api_key)

    return AuthResult(
        allowed_functions=[],
        forbidden_functions=['api::users::delete', 'api::users::update']
            if user['role'] == 'readonly' else [],
        allowed_trigger_types=['cron', 'webhook']
            if user['role'] == 'admin' else None,
        allow_trigger_type_registration=user['role'] == 'admin',
        context={
            'user_id': user['id'],
            'role': user['role'],
        },
    ).model_dump()

iii.register_function("my-project::auth-function", auth_function)

use iii_sdk::{AuthInput, AuthResult, RegisterFunction, register_worker, InitOptions};
use serde_json::json;

let iii = register_worker("ws://localhost:49134", InitOptions::default());

iii.register_function(RegisterFunction::new_async(
    "my-project::auth-function",
    |auth_input: AuthInput| async move {
        let token = auth_input.headers.get("authorization")
            .map(|v| v.trim_start_matches("Bearer ").to_string());
        let api_key = auth_input.query_params.get("api_key")
            .and_then(|v| v.first())
            .cloned();

        let credential = token.or(api_key)
            .ok_or_else(|| iii_sdk::IIIError::Handler("Missing credentials".into()))?;

        let user = validate_credentials(&credential).await?;

        Ok(AuthResult {
            allowed_functions: vec![],
            forbidden_functions: if user.role == "readonly" {
                vec!["api::users::delete".into(), "api::users::update".into()]
            } else {
                vec![]
            },
            allowed_trigger_types: if user.role == "admin" {
                Some(vec!["cron".into(), "webhook".into()])
            } else {
                None
            },
            allow_trigger_type_registration: user.role == "admin",
            context: json!({ "user_id": user.id, "role": user.role }),
            function_registration_prefix: None,
        })
    },
));

Function Registration Prefix

The auth function can optionally return a function_registration_prefix string. When present, the engine automatically prefixes every function ID registered by this worker with {prefix}::. Trigger registrations also auto-prefix the function_id they reference. When the engine dispatches a function invocation back to the worker, the prefix is stripped so the worker SDK finds the correct local handler. This provides transparent namespace isolation per session without the worker needing to manage prefixes. Update your config to reference the auth function:

iii-config.yaml

workers:
  - name: iii-worker-manager
    config:
      port: 49135
      rbac:
        auth_function_id: my-project::auth-function
        expose_functions:
          - match("api::*")

3. Write a Middleware Function (Optional)

A middleware sits between the worker and the target function. Use it for validation, rate limiting, audit logging, or enriching the payload with auth context. The function receives a MiddlewareFunctionInput.

Node / TypeScript
Python
Rust

import type { MiddlewareFunctionInput } from 'iii-sdk'

iii.registerFunction(
  'my-project::middleware-function',
  async (input: MiddlewareFunctionInput) => {
    console.log(`[audit] user=${input.context.user_id} invoking ${input.function_id}`)

    const enrichedPayload = {
      ...input.payload,
      _caller_id: input.context.user_id,
      _caller_role: input.context.role,
    }

    return iii.trigger({
      function_id: input.function_id,
      payload: enrichedPayload,
    })
  },
)

from iii import MiddlewareFunctionInput

async def middleware_function(data: dict) -> dict:
    mid = MiddlewareFunctionInput(**data)

    print(f"[audit] user={mid.context['user_id']} invoking {mid.function_id}")

    enriched_payload = {
        **mid.payload,
        '_caller_id': mid.context['user_id'],
        '_caller_role': mid.context['role'],
    }

    return await iii.trigger_async({
        'function_id': mid.function_id,
        'payload': enriched_payload,
    })

iii.register_function("my-project::middleware-function", middleware_function)

use iii_sdk::{MiddlewareFunctionInput, RegisterFunction, TriggerRequest};
use serde_json::json;

let iii_clone = iii.clone();
iii.register_function(RegisterFunction::new_async(
    "my-project::middleware-function",
    move |input: MiddlewareFunctionInput| {
        let iii = iii_clone.clone();
        async move {
            let mut enriched = input.payload.as_object().cloned().unwrap_or_default();
            enriched.insert("_caller_id".into(), json!(input.context.get("user_id")));
            enriched.insert("_caller_role".into(), json!(input.context.get("role")));

            iii.trigger(TriggerRequest {
                function_id: input.function_id,
                payload: json!(enriched),
                action: None,
                timeout_ms: None,
            }).await
        }
    },
));

Add it to your config. Note that middleware_function_id sits at the config level, not inside rbac:

iii-config.yaml

workers:
  - name: iii-worker-manager
    config:
      port: 49135
      middleware_function_id: my-project::middleware-function
      rbac:
        auth_function_id: my-project::auth-function
        expose_functions:
          - match("api::*")

4. Connect a Worker

The RBAC port speaks the standard iii engine protocol. Connect using the SDK:

Node / TypeScript
Python
Rust

import { registerWorker } from 'iii-sdk'

const worker = registerWorker('ws://localhost:49135', {
  headers: { authorization: 'Bearer my-token' },
})

const result = await worker.trigger({
  function_id: 'api::users::list',
  payload: { limit: 10 },
})

console.log(result)

from iii import InitOptions, register_worker

worker = register_worker(
    'ws://localhost:49135',
    InitOptions(headers={'authorization': 'Bearer my-token'}),
)

result = worker.trigger({
    'function_id': 'api::users::list',
    'payload': {'limit': 10},
})

print(result)

use iii_sdk::{register_worker, InitOptions, TriggerRequest};
use serde_json::json;
use std::collections::HashMap;

let mut headers = HashMap::new();
headers.insert("authorization".into(), "Bearer my-token".into());

let worker = register_worker("ws://localhost:49135", InitOptions {
    headers: Some(headers),
    ..Default::default()
});

let result = worker.trigger(TriggerRequest {
    function_id: "api::users::list".into(),
    payload: json!({ "limit": 10 }),
    action: None,
    timeout_ms: None,
}).await.expect("trigger failed");

5. Use Channels Through the RBAC Port

Channels work on the RBAC port exactly as they do on the main engine port. The SDK’s createChannel() works without changes:

const worker = registerWorker('ws://localhost:49135', {
  headers: { authorization: 'Bearer my-token' },
})

const channel = await worker.createChannel()

const result = await worker.trigger({
  function_id: 'api::files::process',
  payload: { reader: channel.readerRef },
})

channel.writer.stream.write(Buffer.from('hello'))
channel.writer.stream.end()

The RBAC port mounts the channel WebSocket endpoint at /ws/channels/{channel_id} on the same port, so channel data flows through the secure port without exposing the main engine’s channel endpoint.

6. RBAC for Trigger Registration

Workers connecting through the RBAC port can register trigger types and triggers, subject to access control.

Auth Result Fields

The auth function controls trigger access via two fields in AuthResult:

allowed_trigger_types — List of trigger type IDs this worker can register triggers for. When omitted, all types are allowed.
allow_trigger_type_registration — Whether this worker can register new trigger types.

Registration Hook Functions

For fine-grained control, configure hook functions that are called before each registration:

iii-config.yaml

workers:
  - name: iii-worker-manager
    config:
      port: 49135
      middleware_function_id: my-project::middleware-function
      rbac:
        auth_function_id: my-project::auth-function
        on_trigger_registration_function_id: my-project::on-trigger-reg
        on_trigger_type_registration_function_id: my-project::on-trigger-type-reg
        on_function_registration_function_id: my-project::on-function-reg
        expose_functions:
          - match("api::*")

Each hook receives the registration details and the auth context. Return a result object with the (possibly mapped) fields to allow the registration, or throw an error to deny it. Any fields omitted from the result keep their original values.

Node / TypeScript
Python
Rust

import type {
  OnTriggerRegistrationInput,
  OnTriggerRegistrationResult,
  OnTriggerTypeRegistrationInput,
  OnTriggerTypeRegistrationResult,
  OnFunctionRegistrationInput,
  OnFunctionRegistrationResult,
} from 'iii-sdk'

iii.registerFunction(
  'my-project::on-trigger-reg',
  async (input: OnTriggerRegistrationInput): Promise<OnTriggerRegistrationResult> => {
    const role = input.context.role as string
    if (!input.function_id.startsWith(`${role}::`)) {
      throw new Error('Function ID must be prefixed with the role')
    }
    return { function_id: `${role}::${input.function_id}` }
  },
)

iii.registerFunction(
  'my-project::on-trigger-type-reg',
  async (input: OnTriggerTypeRegistrationInput): Promise<OnTriggerTypeRegistrationResult> => {
    if (input.context.role !== 'admin') {
      throw new Error('Only admins can register trigger types')
    }
    return {}
  },
)

iii.registerFunction(
  'my-project::on-function-reg',
  async (input: OnFunctionRegistrationInput): Promise<OnFunctionRegistrationResult> => {
    if (input.function_id.startsWith('internal::')) {
      throw new Error('Cannot register internal functions')
    }
    return { function_id: input.function_id }
  },
)

from iii import (
    OnTriggerRegistrationInput,
    OnTriggerRegistrationResult,
    OnTriggerTypeRegistrationInput,
    OnTriggerTypeRegistrationResult,
    OnFunctionRegistrationInput,
    OnFunctionRegistrationResult,
)

async def on_trigger_reg(data: dict) -> dict:
    inp = OnTriggerRegistrationInput(**data)
    role = inp.context['role']
    if not inp.function_id.startswith(f"{role}::"):
        raise Exception('Function ID must be prefixed with the role')
    return OnTriggerRegistrationResult(
        function_id=f"{role}::{inp.function_id}",
    ).model_dump()

async def on_trigger_type_reg(data: dict) -> dict:
    inp = OnTriggerTypeRegistrationInput(**data)
    if inp.context['role'] != 'admin':
        raise Exception('Only admins can register trigger types')
    return OnTriggerTypeRegistrationResult().model_dump()

async def on_function_reg(data: dict) -> dict:
    inp = OnFunctionRegistrationInput(**data)
    if inp.function_id.startswith('internal::'):
        raise Exception('Cannot register internal functions')
    return OnFunctionRegistrationResult(
        function_id=inp.function_id,
    ).model_dump()

iii.register_function("my-project::on-trigger-reg", on_trigger_reg)
iii.register_function("my-project::on-trigger-type-reg", on_trigger_type_reg)
iii.register_function("my-project::on-function-reg", on_function_reg)

use iii_sdk::{
    OnTriggerRegistrationInput, OnTriggerRegistrationResult,
    OnTriggerTypeRegistrationInput, OnTriggerTypeRegistrationResult,
    OnFunctionRegistrationInput, OnFunctionRegistrationResult,
    RegisterFunction,
};

iii.register_function(RegisterFunction::new_async(
    "my-project::on-trigger-reg",
    |input: OnTriggerRegistrationInput| async move {
        let role = input.context.get("role").and_then(|v| v.as_str()).unwrap_or("");
        let prefix = format!("{role}::");
        if !input.function_id.starts_with(&prefix) {
            return Err(iii_sdk::IIIError::Handler("Function ID must be prefixed with the role".into()));
        }
        Ok(OnTriggerRegistrationResult {
            function_id: Some(format!("{role}::{}", input.function_id)),
            ..Default::default()
        })
    },
));

iii.register_function(RegisterFunction::new_async(
    "my-project::on-trigger-type-reg",
    |input: OnTriggerTypeRegistrationInput| async move {
        let role = input.context.get("role").and_then(|v| v.as_str()).unwrap_or("");
        if role != "admin" {
            return Err(iii_sdk::IIIError::Handler("Only admins can register trigger types".into()));
        }
        Ok(OnTriggerTypeRegistrationResult::default())
    },
));

iii.register_function(RegisterFunction::new_async(
    "my-project::on-function-reg",
    |input: OnFunctionRegistrationInput| async move {
        if input.function_id.starts_with("internal::") {
            return Err(iii_sdk::IIIError::Handler("Cannot register internal functions".into()));
        }
        Ok(OnFunctionRegistrationResult {
            function_id: Some(input.function_id),
            ..Default::default()
        })
    },
));

Expose Functions by Metadata

If your functions register metadata, you can use metadata filters instead of (or in addition to) wildcard patterns:

Node / TypeScript
Python
Rust

iii.registerFunction('api::users::list', async (input) => {
  // ...
}, { metadata: { public: true, tier: 'free' } })

iii.register_function("api::users::list", list_users, metadata={'public': True, 'tier': 'free'})

let mut msg = RegisterFunctionMessage::with_id("api::users::list".to_string());
msg.metadata = Some(json!({ "public": true, "tier": "free" }));

iii.register_function((msg, |input: Value| async move {
    // ...
    Ok(json!({}))
}));

Then filter by metadata in your config:

iii-config.yaml

rbac:
  expose_functions:
    - metadata:
        public: true
    - metadata:
        tier: "free"

Types Reference

All three SDKs export the following types for RBAC functions.

AuthInput

Input passed to the auth function during the WebSocket upgrade.

Field	Type	Description
`headers`	`Record<string, string>`	HTTP headers from the upgrade request.
`query_params`	`Record<string, string[]>`	Query parameters. Each key maps to an array of values to support repeated keys.
`ip_address`	`string`	IP address of the connecting client.

AuthResult

Return value from the auth function. Controls access and passes context to middleware.

Field	Type	Default	Description
`allowed_functions`	`string[]`	`[]`	Additional function IDs to allow beyond `expose_functions`.
`forbidden_functions`	`string[]`	`[]`	Function IDs to deny even if they match `expose_functions`. Takes precedence.
`allowed_trigger_types`	`string[]` or omitted	omitted (permissive)	Trigger type IDs the worker may register triggers for. When omitted, all types are allowed.
`allow_trigger_type_registration`	`boolean`	`false`	Whether the worker may register new trigger types.
`allow_function_registration`	`boolean`	`true`	Whether the worker may register new functions.
`function_registration_prefix`	`string` or omitted	omitted	When set, all function IDs registered by this worker are internally prefixed with `{prefix}::`. Triggers auto-prefix their `function_id` reference. The prefix is stripped when invoking the worker, so the worker SDK never sees it.
`context`	`Record<string, unknown>`	`{}`	Arbitrary context forwarded to the middleware function on every invocation.

MiddlewareFunctionInput

Input passed to the middleware function on every invocation through the RBAC port.

Field	Type	Description
`function_id`	`string`	ID of the function being invoked.
`payload`	`Record<string, unknown>`	Payload sent by the caller.
`action`	`TriggerAction` or omitted	Routing action (enqueue, void), if any.
`context`	`Record<string, unknown>`	Auth context from `AuthResult.context` for this session.

OnTriggerTypeRegistrationInput

Input passed to the on_trigger_type_registration_function_id hook. Return an OnTriggerTypeRegistrationResult or throw to deny.

Field	Type	Description
`trigger_type_id`	`string`	ID of the trigger type being registered.
`description`	`string`	Human-readable description of the trigger type.
`context`	`Record<string, unknown>`	Auth context from `AuthResult.context`.

OnTriggerTypeRegistrationResult

Result returned from the on_trigger_type_registration_function_id hook. Omitted fields keep the original value.

Field	Type	Description
`trigger_type_id`	`string` or omitted	Mapped trigger type ID.
`description`	`string` or omitted	Mapped description.

OnTriggerRegistrationInput

Input passed to the on_trigger_registration_function_id hook. Return an OnTriggerRegistrationResult or throw to deny.

Field	Type	Description
`trigger_id`	`string`	ID of the trigger being registered.
`trigger_type`	`string`	Trigger type identifier.
`function_id`	`string`	ID of the function this trigger is bound to.
`config`	`unknown`	Trigger-specific configuration.
`context`	`Record<string, unknown>`	Auth context from `AuthResult.context`.

OnTriggerRegistrationResult

Result returned from the on_trigger_registration_function_id hook. Omitted fields keep the original value.

Field	Type	Description
`trigger_id`	`string` or omitted	Mapped trigger ID.
`trigger_type`	`string` or omitted	Mapped trigger type.
`function_id`	`string` or omitted	Mapped function ID.
`config`	`unknown` or omitted	Mapped trigger configuration.

OnFunctionRegistrationInput

Input passed to the on_function_registration_function_id hook. Return an OnFunctionRegistrationResult or throw to deny.

Field	Type	Description
`function_id`	`string`	ID of the function being registered.
`description`	`string` or omitted	Human-readable description of the function.
`metadata`	`Record<string, unknown>` or omitted	Arbitrary metadata attached to the function.
`context`	`Record<string, unknown>`	Auth context from `AuthResult.context`.

OnFunctionRegistrationResult

Result returned from the on_function_registration_function_id hook. Omitted fields keep the original value.

Field	Type	Description
`function_id`	`string` or omitted	Mapped function ID.
`description`	`string` or omitted	Mapped description.
`metadata`	`Record<string, unknown>` or omitted	Mapped metadata.

Full Example Config

iii-config.yaml

workers:
  - name: iii-worker-manager
    config:
      port: 49134

  - name: iii-stream
    config:
      port: 3112

  - name: iii-worker-manager
    config:
      host: 0.0.0.0
      port: 49135
      middleware_function_id: my-project::middleware-function
      rbac:
        auth_function_id: my-project::auth-function
        on_trigger_registration_function_id: my-project::on-trigger-reg
        on_trigger_type_registration_function_id: my-project::on-trigger-type-reg
        on_function_registration_function_id: my-project::on-function-reg
        expose_functions:
          - match("api::*")
          - match("*::public")
          - metadata:
              public: true

Only expose the RBAC port (49135) to external networks. The main engine port (49134) and stream port (3112) should remain internal. Use firewall rules or network policies to enforce this.

Getting Started

Primitives & Concepts

How-to Guides

Architecture

Workers

Console

Advanced

Examples

Worker RBAC

1. Add RBAC Config to the Worker Manager

2. Write an Auth Function

Function Registration Prefix

3. Write a Middleware Function (Optional)

4. Connect a Worker

5. Use Channels Through the RBAC Port

6. RBAC for Trigger Registration

Auth Result Fields

Registration Hook Functions

Expose Functions by Metadata

Types Reference

AuthInput

AuthResult

MiddlewareFunctionInput

OnTriggerTypeRegistrationInput

OnTriggerTypeRegistrationResult

OnTriggerRegistrationInput

OnTriggerRegistrationResult

OnFunctionRegistrationInput

OnFunctionRegistrationResult

Full Example Config

​1. Add RBAC Config to the Worker Manager

​2. Write an Auth Function

​Function Registration Prefix

​3. Write a Middleware Function (Optional)

​4. Connect a Worker

​5. Use Channels Through the RBAC Port

​6. RBAC for Trigger Registration

​Auth Result Fields

​Registration Hook Functions

​Expose Functions by Metadata

​Types Reference

​AuthInput

​AuthResult

​MiddlewareFunctionInput

​OnTriggerTypeRegistrationInput

​OnTriggerTypeRegistrationResult

​OnTriggerRegistrationInput

​OnTriggerRegistrationResult

​OnFunctionRegistrationInput

​OnFunctionRegistrationResult

​Full Example Config

1. Add RBAC Config to the Worker Manager

2. Write an Auth Function

Function Registration Prefix

3. Write a Middleware Function (Optional)

4. Connect a Worker

5. Use Channels Through the RBAC Port

6. RBAC for Trigger Registration

Auth Result Fields

Registration Hook Functions

Expose Functions by Metadata

Types Reference

AuthInput

AuthResult

MiddlewareFunctionInput

OnTriggerTypeRegistrationInput

OnTriggerTypeRegistrationResult

OnTriggerRegistrationInput

OnTriggerRegistrationResult

OnFunctionRegistrationInput

OnFunctionRegistrationResult

Full Example Config