Authorization API Reference

February 2, 2026 · View on GitHub

Complete API reference for authorization and RBAC operations in the Conductor Rust SDK.

Note: Authorization APIs are available with Orkes Conductor.

Quick Start
AuthorizationClient API
Applications
Users
Groups
Permissions
Roles
Access Keys
Models Reference
Best Practices

Quick Start

use conductor::{Configuration, ConductorClient};
use conductor::models::{
    CreateOrUpdateApplicationRequest, UpsertUserRequest, UpsertGroupRequest,
    SubjectRef, TargetRef, AccessType, SubjectType, TargetType,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Configuration::new("https://play.orkes.io/api")
        .with_auth("KEY_ID", "KEY_SECRET");
    
    let client = ConductorClient::new(config)?;
    let auth_client = client.authorization_client();

    // Create an application
    let app_request = CreateOrUpdateApplicationRequest::new("my-service");
    let app = auth_client.create_application(&app_request).await?;
    println!("Created application: {}", app.id);

    // Create a user
    let user_request = UpsertUserRequest::new("John Doe")
        .with_roles(vec!["USER".to_string()]);
    let user = auth_client.upsert_user(&user_request, "john@example.com").await?;
    println!("Created user: {}", user.id);

    // Grant permissions
    let subject = SubjectRef::new(SubjectType::User, "john@example.com");
    let target = TargetRef::new(TargetType::WorkflowDef, "my_workflow");
    auth_client.grant_permissions(&subject, &target, &[AccessType::Read, AccessType::Execute]).await?;

    Ok(())
}

AuthorizationClient API

Application APIs

Method	Description
`create_application()`	Create a new application
`get_application()`	Get application by ID
`list_applications()`	List all applications
`update_application()`	Update an application
`delete_application()`	Delete an application
`get_app_by_access_key_id()`	Get app ID from access key

User APIs

Method	Description
`upsert_user()`	Create or update a user
`get_user()`	Get user by ID
`list_users()`	List all users
`delete_user()`	Delete a user
`get_granted_permissions_for_user()`	Get user's permissions
`check_permissions()`	Check if user has permission

Group APIs

Method	Description
`upsert_group()`	Create or update a group
`get_group()`	Get group by ID
`list_groups()`	List all groups
`delete_group()`	Delete a group
`add_user_to_group()`	Add user to group
`add_users_to_group()`	Add multiple users
`get_users_in_group()`	Get users in group
`remove_user_from_group()`	Remove user from group
`remove_users_from_group()`	Remove multiple users
`get_granted_permissions_for_group()`	Get group's permissions

Permission APIs

Method	Description
`grant_permissions()`	Grant permissions to subject
`get_permissions()`	Get permissions for target
`remove_permissions()`	Remove permissions

Role APIs

Method	Description
`list_all_roles()`	List all roles
`list_system_roles()`	List system roles
`list_custom_roles()`	List custom roles
`list_available_permissions()`	List available permissions
`create_role()`	Create custom role
`get_role()`	Get role by name
`update_role()`	Update custom role
`delete_role()`	Delete custom role

Access Key APIs

Method	Description
`create_access_key()`	Create access key for app
`get_access_keys()`	Get app's access keys
`toggle_access_key_status()`	Enable/disable key
`delete_access_key()`	Delete access key
`add_role_to_application_user()`	Add role to app
`remove_role_from_application_user()`	Remove role from app

Applications

Create Application

use conductor::models::CreateOrUpdateApplicationRequest;

let request = CreateOrUpdateApplicationRequest::new("payment-service");
let app = auth_client.create_application(&request).await?;

println!("Application ID: {}", app.id);
println!("Application Name: {}", app.name);

Get Application

let app = auth_client.get_application("app-id-123").await?;
println!("Application: {} ({})", app.name, app.id);

List Applications

let apps = auth_client.list_applications().await?;

for app in &apps {
    println!("{}: {}", app.id, app.name);
}

Update Application

let request = CreateOrUpdateApplicationRequest::new("payment-service-v2");
let updated = auth_client.update_application(&request, "app-id-123").await?;

Delete Application

auth_client.delete_application("app-id-123").await?;

Application Tags

use conductor::models::MetadataTag;

// Set tags
let tags = vec![
    MetadataTag::new("environment", "production"),
    MetadataTag::new("team", "payments"),
];
auth_client.set_application_tags(&tags, "app-id-123").await?;

// Get tags
let tags = auth_client.get_application_tags("app-id-123").await?;

// Delete tags
auth_client.delete_application_tags(&[
    MetadataTag::new("team", "payments"),
], "app-id-123").await?;

Users

Create or Update User

use conductor::models::UpsertUserRequest;

let request = UpsertUserRequest::new("John Doe")
    .with_roles(vec!["USER".to_string(), "METADATA_MANAGER".to_string()]);

let user = auth_client.upsert_user(&request, "john@example.com").await?;
println!("User created: {}", user.id);

Get User

let user = auth_client.get_user("john@example.com").await?;

println!("User: {}", user.name);
println!("Roles: {:?}", user.roles);
println!("Groups: {:?}", user.groups);

List Users

// List human users only
let users = auth_client.list_users(false).await?;

// Include application users
let all_users = auth_client.list_users(true).await?;

for user in &users {
    println!("{}: {} ({:?})", user.id, user.name, user.roles);
}

Delete User

auth_client.delete_user("john@example.com").await?;

Get User Permissions

let permissions = auth_client.get_granted_permissions_for_user("john@example.com").await?;

for perm in &permissions {
    println!("Target: {:?}:{}", perm.target.target_type, perm.target.id);
    println!("Access: {:?}", perm.access);
}

Check Permissions

let result = auth_client.check_permissions(
    "john@example.com",
    "WORKFLOW_DEF",
    "my_workflow",
).await?;

for (permission, granted) in &result {
    println!("{}: {}", permission, granted);
}

Groups

Create or Update Group

use conductor::models::UpsertGroupRequest;

let request = UpsertGroupRequest::new("Engineering Team")
    .with_roles(vec!["USER".to_string(), "WORKFLOW_MANAGER".to_string()]);

let group = auth_client.upsert_group(&request, "engineering-team").await?;
println!("Group created: {}", group.id);

Get Group

let group = auth_client.get_group("engineering-team").await?;

println!("Group: {} ({})", group.id, group.description);
println!("Roles: {:?}", group.roles);

List Groups

let groups = auth_client.list_groups().await?;

for group in &groups {
    println!("{}: {}", group.id, group.description);
}

Manage Group Members

// Add single user
auth_client.add_user_to_group("engineering-team", "john@example.com").await?;

// Add multiple users
auth_client.add_users_to_group("engineering-team", &[
    "jane@example.com".to_string(),
    "bob@example.com".to_string(),
]).await?;

// Get users in group
let users = auth_client.get_users_in_group("engineering-team").await?;
for user in &users {
    println!("  {}: {}", user.id, user.name);
}

// Remove single user
auth_client.remove_user_from_group("engineering-team", "bob@example.com").await?;

// Remove multiple users
auth_client.remove_users_from_group("engineering-team", &[
    "john@example.com".to_string(),
]).await?;

Delete Group

auth_client.delete_group("engineering-team").await?;

Permissions

Grant Permissions

use conductor::models::{SubjectRef, TargetRef, AccessType, SubjectType, TargetType};

// Grant to user
let subject = SubjectRef::new(SubjectType::User, "john@example.com");
let target = TargetRef::new(TargetType::WorkflowDef, "order_workflow");

auth_client.grant_permissions(
    &subject,
    &target,
    &[AccessType::Read, AccessType::Execute],
).await?;

// Grant to group
let group_subject = SubjectRef::new(SubjectType::Group, "engineering-team");
auth_client.grant_permissions(
    &group_subject,
    &target,
    &[AccessType::Read, AccessType::Execute, AccessType::Update],
).await?;

Get Permissions

let target = TargetRef::new(TargetType::WorkflowDef, "order_workflow");
let permissions = auth_client.get_permissions(&target).await?;

for (access_type, subjects) in &permissions {
    println!("{}:", access_type);
    for subject in subjects {
        println!("  {:?}: {}", subject.subject_type, subject.id);
    }
}

Remove Permissions

let subject = SubjectRef::new(SubjectType::User, "john@example.com");
let target = TargetRef::new(TargetType::WorkflowDef, "order_workflow");

auth_client.remove_permissions(
    &subject,
    &target,
    &[AccessType::Execute],  // Remove only execute permission
).await?;

Roles

List Roles

// All roles
let all_roles = auth_client.list_all_roles().await?;

// System roles only
let system_roles = auth_client.list_system_roles().await?;

// Custom roles only
let custom_roles = auth_client.list_custom_roles().await?;

Create Custom Role

let role_def = serde_json::json!({
    "name": "workflow-operator",
    "description": "Can execute and monitor workflows",
    "permissions": [
        {
            "resource": "WORKFLOW_DEF",
            "actions": ["READ", "EXECUTE"]
        },
        {
            "resource": "WORKFLOW",
            "actions": ["READ", "EXECUTE"]
        }
    ]
});

let role = auth_client.create_role(&role_def).await?;
println!("Created role: {:?}", role);

Get Role

let role = auth_client.get_role("workflow-operator").await?;
println!("Role: {:?}", role);

Update Role

let update = serde_json::json!({
    "description": "Updated description",
    "permissions": [
        {
            "resource": "WORKFLOW_DEF",
            "actions": ["READ", "EXECUTE", "UPDATE"]
        }
    ]
});

let updated = auth_client.update_role("workflow-operator", &update).await?;

Delete Role

auth_client.delete_role("workflow-operator").await?;

Access Keys

Create Access Key

let access_key = auth_client.create_access_key("app-id-123").await?;

// IMPORTANT: Save these immediately - secret is only shown once!
println!("Key ID: {}", access_key.id);
println!("Key Secret: {}", access_key.secret);

Get Access Keys

let keys = auth_client.get_access_keys("app-id-123").await?;

for key in &keys {
    println!("Key: {} - {:?}", key.id, key.status);
}

Toggle Key Status

let key = auth_client.toggle_access_key_status("app-id-123", "key-id").await?;
println!("New status: {:?}", key.status);

Delete Access Key

auth_client.delete_access_key("app-id-123", "key-id").await?;

Application Roles

// Add role to application
auth_client.add_role_to_application_user("app-id-123", "ADMIN").await?;

// Remove role
auth_client.remove_role_from_application_user("app-id-123", "ADMIN").await?;

Models Reference

SubjectRef

pub struct SubjectRef {
    pub subject_type: SubjectType,
    pub id: String,
}

pub enum SubjectType {
    User,
    Group,
    Role,
}

TargetRef

pub struct TargetRef {
    pub target_type: TargetType,
    pub id: String,
}

pub enum TargetType {
    WorkflowDef,
    TaskDef,
    Application,
    User,
    SecretName,
    Domain,
    // ... more types
}

AccessType

pub enum AccessType {
    Read,
    Create,
    Update,
    Execute,
    Delete,
}

System Roles

Role	Description
`USER`	Basic user access
`ADMIN`	Full administrative access
`METADATA_MANAGER`	Manage workflow/task definitions
`WORKFLOW_MANAGER`	Manage workflow executions
`WORKER`	Worker task execution access

Best Practices

1. Use Groups for Permissions

// Instead of granting to individual users
// Grant to groups and add users to groups

let group_request = UpsertGroupRequest::new("Workflow Operators")
    .with_roles(vec!["USER".to_string()]);
auth_client.upsert_group(&group_request, "workflow-operators").await?;

// Grant permissions to group
let subject = SubjectRef::new(SubjectType::Group, "workflow-operators");
let target = TargetRef::new(TargetType::WorkflowDef, "order_workflow");
auth_client.grant_permissions(&subject, &target, &[AccessType::Read, AccessType::Execute]).await?;

// Add users to group
auth_client.add_users_to_group("workflow-operators", &[
    "user1@example.com".to_string(),
    "user2@example.com".to_string(),
]).await?;

2. Secure Access Keys

// Create access key and store securely
let key = auth_client.create_access_key(&app.id).await?;

// Store in secure vault/secrets manager
store_in_vault("conductor_key_id", &key.id);
store_in_vault("conductor_key_secret", &key.secret);

// Rotate keys periodically
async fn rotate_key(client: &AuthorizationClient, app_id: &str) -> Result<()> {
    // Create new key
    let new_key = client.create_access_key(app_id).await?;
    
    // Update application to use new key
    // ...
    
    // Delete old key
    let old_keys = client.get_access_keys(app_id).await?;
    for key in old_keys.iter().filter(|k| k.id != new_key.id) {
        client.delete_access_key(app_id, &key.id).await?;
    }
    
    Ok(())
}

3. Audit Permissions

async fn audit_workflow_access(client: &AuthorizationClient, workflow_name: &str) -> Result<()> {
    let target = TargetRef::new(TargetType::WorkflowDef, workflow_name);
    let permissions = client.get_permissions(&target).await?;
    
    println!("Access audit for workflow: {}", workflow_name);
    println!("==========================================");
    
    for (access_type, subjects) in &permissions {
        println!("\n{} access:", access_type);
        for subject in subjects {
            match subject.subject_type {
                SubjectType::User => {
                    let user = client.get_user(&subject.id).await?;
                    println!("  User: {} ({})", user.name, subject.id);
                }
                SubjectType::Group => {
                    let group = client.get_group(&subject.id).await?;
                    println!("  Group: {} ({} members)", subject.id, 
                        client.get_users_in_group(&subject.id).await?.len());
                }
                _ => println!("  {:?}: {}", subject.subject_type, subject.id),
            }
        }
    }
    
    Ok(())
}