API Filtering

Filter Parameter

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

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

Supported Operators

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/[email protected]

# 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)