Users API

Overview

The Users API provides endpoints for managing Faction user accounts, including creating users, setting permissions, and enabling/disabling accounts. This API is restricted to administrators and certain operations are limited by the Faction tier. All endpoints require authentication via the FACTION-API-KEY header and Admin role permissions.

Add User

curl -X POST "https://your-faction-instance.com/api/users/addUser" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=jdoe" \
  -d "[email protected]" \
  -d "fname=John" \
  -d "lname=Doe" \
  -d "team=Security Team" \
  -d "authMethod=LDAP" \
  -d "verify=true" \
  -d "isAssessor=true" \
  -d "isManager=false"

Creates a new user in Faction with specified roles and permissions.

Authentication

FACTION-API-KEY

string

required

API authentication key (requires Admin role)

Form Parameters

username

string

required

Username for the new account

string

required

Email address

fname

string

required

First name

lname

string

required

Last name

team

string

required

Team name (must already exist in the system)

authMethod

string

required

Authentication method (e.g., “LDAP”, “LOCAL”, “SSO”)

verify

boolean

Send verification email to user. If true, sends a registration link to the user’s email address.

isAssessor

boolean

Grant Assessor role permissions

isAdmin

boolean

Grant Admin role permissions

isRemediation

boolean

Grant Remediation role permissions

isEngage

boolean

Grant Engagement/Scheduler role permissions

isManager

boolean

Grant Manager role permissions

User Roles

Show Role Descriptions

Assessor

Conduct security assessments
Add and manage vulnerabilities
Access assessment queue
View assigned assessments

Admin

Manage users and teams
Configure system settings
Access audit logs
Full system access

Remediation

View vulnerabilities
Track remediation status
Update vulnerability statuses
Access remediation tracking

Engagement/Scheduler

Create assessments
Schedule assessments to assessors
Manage assessment lifecycle
Configure assessment parameters

Manager

View all assessments
Manage vulnerabilities
Access reports
Oversight capabilities

Verification Email

When verify=true:

A random password is generated and hashed
A registration link is sent to the user’s email
User must click the link to set their password
Account cannot be accessed until password is set

Status Codes

200 - Success: User created
400 - User already exists, invalid username, or team doesn’t exist
401 - Not authorized (requires Admin role)

Notes

This endpoint is not available in the “consultant” tier
If a user with the same username already exists, the request will fail
The specified team must exist in the system before creating the user
Multiple roles can be assigned to a single user

Disable User

curl -X POST "https://your-faction-instance.com/api/users/disableUser" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=jdoe"

Sets a user account to inactive state. The user will not be able to log in until the account is unlocked.

Authentication

FACTION-API-KEY

string

required

API authentication key (requires Admin role)

Form Parameters

username

string

required

Username to deactivate

Status Codes

200 - Success: User disabled
401 - Not authorized or multiple users with same username
400 - Error occurred

Notes

This endpoint is not available in the “consultant” tier
Disabled users cannot log in until their account is unlocked
User data and history are preserved

Unlock User

curl -X POST "https://your-faction-instance.com/api/users/unlockUser" \
  -H "FACTION-API-KEY: your-api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=jdoe" \
  -d "uioli=true"

Reactivates a disabled user account and optionally resets the “use it or lose it” inactivity timer.

Authentication

FACTION-API-KEY

string

required

API authentication key (requires Admin role)

Form Parameters

username

string

required

Username to activate

uioli

boolean

Reset the “use it or lose it” inactivity timer. When true, updates the last login timestamp to prevent the account from being automatically disabled due to inactivity.

Use It or Lose It (UIOLI)

The uioli parameter controls the inactivity timer:

When set to true, the user’s last login date is updated to the current date
This prevents the account from being automatically disabled for inactivity
Useful when unlocking accounts that have been inactive for extended periods

Status Codes

200 - Success: User unlocked
401 - Not authorized or multiple users with same username
400 - Error occurred

Notes

This endpoint is not available in the “consultant” tier
Unlocking a user immediately allows them to log in
Use the uioli parameter to prevent immediate re-locking due to inactivity policies

Authorization Requirements

All Users API endpoints require:

Valid FACTION-API-KEY header
Admin role permissions
Non-consultant tier instance

User Management Workflow

Create User

Use the Add User endpoint to create a new account with appropriate roles

Send Verification (Optional)

If verify=true, user receives email with registration link

User Sets Password

User clicks link and sets their password (if verification enabled)

User Access

User can now log in with assigned roles and permissions

Disable if Needed

Use Disable User endpoint to temporarily revoke access

Unlock When Ready

Use Unlock User endpoint to restore access

Integration Examples

SSO Integration

When integrating with SSO:

Set authMethod to your SSO provider (e.g., “SAML”, “OAuth2”)
Set verify=false to skip email verification
User account is created with empty password
Authentication is handled by SSO provider

curl -X POST "https://your-faction-instance.com/api/users/addUser" \
  -H "FACTION-API-KEY: your-api-key" \
  -d "username=jdoe" \
  -d "[email protected]" \
  -d "fname=John" \
  -d "lname=Doe" \
  -d "team=Security Team" \
  -d "authMethod=SAML" \
  -d "verify=false" \
  -d "isAssessor=true"

Automated User Provisioning

For automated provisioning workflows:

Create user with verify=true
System sends registration email automatically
User completes self-service registration
No manual password distribution needed

Error Handling

Common Errors

User Already Exists

[{ "result": "ERROR", "message": "User Already Exists" }]

Invalid Team

[{ "result": "ERROR", "message": "Team Name Does not exist" }]

Not Authorized

[{ "result": "ERROR", "message": "Not Authorized" }]

Invalid Username

[{ "result": "ERROR", "message": "User Name Invalid" }]

Best Practices

Role Assignment: Only assign roles that users actually need
Team Organization: Ensure teams are created before adding users
Email Verification: Use verify=true for better security unless using SSO
Regular Audits: Periodically review and disable unused accounts
UIOLI Management: Use the uioli parameter when unlocking long-inactive accounts

Overview

Endpoints

Overview

Add User

Authentication

Form Parameters

User Roles

Verification Email

Status Codes

Notes

Disable User

Authentication

Form Parameters

Status Codes

Notes

Unlock User

Authentication

Form Parameters

Use It or Lose It (UIOLI)

Status Codes

Notes

Authorization Requirements

User Management Workflow

Integration Examples

SSO Integration

Automated User Provisioning

Error Handling

Common Errors

Best Practices

Build docs developers (and LLMs) love

Overview

Endpoints

​Overview

​Add User

​Authentication

​Form Parameters

​User Roles

​Verification Email

​Status Codes

​Notes

​Disable User

​Authentication

​Form Parameters

​Status Codes

​Notes

​Unlock User

​Authentication

​Form Parameters

​Use It or Lose It (UIOLI)

​Status Codes

​Notes

​Authorization Requirements

​User Management Workflow

​Integration Examples

​SSO Integration

​Automated User Provisioning

​Error Handling

​Common Errors

​Best Practices

Build docs developers (and LLMs) love

Overview

Add User

Authentication

Form Parameters

User Roles

Verification Email

Status Codes

Notes

Disable User

Authentication

Form Parameters

Status Codes

Notes

Unlock User

Authentication

Form Parameters

Use It or Lose It (UIOLI)

Status Codes

Notes

Authorization Requirements

User Management Workflow

Integration Examples

SSO Integration

Automated User Provisioning

Error Handling

Common Errors

Best Practices