Filter Parameter

Use the filter query parameter to filter API responses. The format is:

filter=field1{operator}value1,field2{operator}value2

Supported Operators

Operator	Description	Example
`=`	Equals (case-insensitive for strings)	`username=john`
`>`	Greater than	`uid>1000`
`<`	Less than	`uid<5000`
`>=`	Greater than or equal	`gid>=100`
`<=`	Less than or equal	`created<=2024-01-01T00:00:00Z`

Field Types

Different field types have different behaviors:

String fields: Case-insensitive matching. Supports wildcards with *
Number fields: Numeric comparison
Datetime fields: ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
Boolean fields: Use True or False (case-sensitive)

Endpoints Supporting Filters

1. Users Endpoint (`/api/v1/users/`)

Filter users by various fields.

Available Fields

String Fields:

username - Username (supports wildcards)
email - Email address (supports wildcards)
first_name - First name (supports wildcards)
last_name - Last name (supports wildcards)
github_username - GitHub username (supports wildcards)
shell - Shell path (supports wildcards)

Number Fields:

uid - User ID
gid - Group ID

Datetime Fields:

created - Account creation date

Boolean Fields:

is_eng_user - Whether user is an engineering user
is_posix_user - Whether user is a POSIX user
is_active - Whether user is active (checks both local and remote status)
active - Alias for is_active

Examples

# Get users with username "john"
GET /api/v1/users/?filter=username=john

# Get users with UID greater than 1000
GET /api/v1/users/?filter=uid>1000

# Get active users created after a specific date
GET /api/v1/users/?filter=is_active=True,created>=2024-01-01T00:00:00Z

# Get users with email matching a pattern (wildcard)
GET /api/v1/users/?filter=email=*@example.com

# Combine multiple filters
GET /api/v1/users/?filter=username=john,uid>1000,is_active=True

2. Groups Endpoint (`/api/v1/groups/`)

Filter groups by various fields.

Available Fields

String Fields:

name - Group name (supports wildcards)

Number Fields:

gid - Group ID

Boolean Fields:

is_posix_group - Whether group is a POSIX group
synced - Whether group is synced from external source

Examples

# Get groups with name "admin"
GET /api/v1/groups/?filter=name=admin

# Get POSIX groups with GID greater than 100
GET /api/v1/groups/?filter=is_posix_group=True,gid>100

# Get synced groups
GET /api/v1/groups/?filter=synced=True

# Get groups with name matching a pattern
GET /api/v1/groups/?filter=name=*admin*

3. Group Members Endpoint (`/api/v1/groups/{groupname}/members/`)

Filter group members by various fields.

Available Fields

String Fields:

username - Username of the member (supports wildcards)

Datetime Fields:

expires - Membership expiration date

Examples

# Get members with username "john"
GET /api/v1/groups/admins/members/?filter=username=john

# Get members whose membership expires after a specific date
GET /api/v1/groups/admins/members/?filter=expires>=2024-12-31T23:59:59Z

# Get members with username matching a pattern
GET /api/v1/groups/admins/members/?filter=username=*admin*

4. Client Certificates Endpoint (`/api/v1/eap_tls/client_certificates/`)

Filter client certificates by various fields.

Available Fields

String Fields:

cn - Common Name (supports wildcards)
san - Subject Alternative Name (supports wildcards)
serial - Certificate serial number (supports wildcards)
radius_certificate_authority__serial - CA serial number (supports wildcards)

Datetime Fields:

expires - Certificate expiration date
created - Certificate creation date
revoked_on - Certificate revocation date

Boolean Fields:

revoked - Whether certificate is revoked

Examples

# Get certificates with specific CN
GET /api/v1/eap_tls/client_certificates/?filter=cn=user@example.com

# Get non-revoked certificates expiring after a date
GET /api/v1/eap_tls/client_certificates/?filter=revoked=False,expires>=2024-12-31T23:59:59Z

# Get certificates created before a date
GET /api/v1/eap_tls/client_certificates/?filter=created<=2024-01-01T00:00:00Z

# Get certificates with CN matching a pattern
GET /api/v1/eap_tls/client_certificates/?filter=cn=*@example.com

Wildcard Matching

String fields support wildcard matching using the * character. The * matches any sequence of characters.

Examples:

username=*admin* - Matches usernames containing "admin"
email=*@example.com - Matches all emails from example.com domain
name=test* - Matches names starting with "test"

Datetime Format

All datetime fields must use ISO 8601 format in UTC:

YYYY-MM-DDTHH:MM:SSZ

Examples:

2024-01-01T00:00:00Z - January 1, 2024, midnight UTC
2024-12-31T23:59:59Z - December 31, 2024, 11:59:59 PM UTC

Boolean Values

Boolean fields accept only the string values True or False (case-sensitive).

Examples:

is_active=True
is_posix_user=False
revoked=False

Combining Filters

Multiple filters can be combined by separating them with commas. All filters are applied with AND logic (all conditions must be met).

Example:

GET /api/v1/users/?filter=username=john,uid>1000,is_active=True

This returns users where:

Username equals "john" AND
UID is greater than 1000 AND
User is active

URL Encoding

When using filters in URLs, ensure proper URL encoding:

Spaces should be encoded as %20 or +
Special characters should be URL encoded
Commas separating filters should not be encoded

Example:

# URL encoded version
GET /api/v1/users/?filter=username=john%20doe,uid>1000

Combining with Pagination

Filters can be combined with pagination parameters:

GET /api/v1/users/?filter=is_active=True&page=1&limit=50

Error Handling

If an invalid field or operator is used, the filter will be ignored. Only valid filters matching the endpoint's supported fields will be applied.

Notes

String comparisons are case-insensitive when using the = operator
Wildcard matching uses regex patterns (case-insensitive)
Boolean fields for is_active and active check both is_active_local and is_active_remote when set to True
The synced field checks for the presence of external_id (True = synced, False = not synced)

Sign up now