ABAC (Attribute-Based Access Control)

Overview

The ABAC (Attribute-Based Access Control) API provides endpoints for managing user attributes and implementing attribute-based access control. You can set attributes such as age, department, certifications, and authentication level, and combine them with policies for flexible access control.

Endpoint List

Method	Endpoint	Description
GET	`/api/admin/attributes`	List attribute definitions
POST	`/api/admin/attributes`	Create attribute definition
GET	`/api/admin/attributes/users/:userId`	Get user attributes
PUT	`/api/admin/attributes/users/:userId`	Update user attributes
DELETE	`/api/admin/attributes/users/:userId/:key`	Delete user attribute
GET	`/api/admin/attributes/verifications`	List verification history
POST	`/api/admin/attributes/verifications`	Execute attribute verification
GET	`/api/admin/attributes/stats`	Get attribute statistics
POST	`/api/admin/attributes/bulk/cleanup-expired`	Bulk delete expired attributes

List Attribute Definitions

Retrieve attribute definitions for the tenant.

Endpoint

GET /api/admin/attributes

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	-	Number of items (default: 50)
`cursor`	string	-	Pagination cursor
`category`	string	-	Filter by category

Request Example

curl -X GET "https://{tenant-domain}/api/admin/attributes" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "key": "age_verified",
      "display_name": "Age Verified",
      "description": "User's age verification status",
      "type": "boolean",
      "category": "verification",
      "required": false,
      "default_value": false,
      "created_at": 1705881600
    },
    {
      "key": "department",
      "display_name": "Department",
      "description": "Department affiliation",
      "type": "string",
      "category": "organization",
      "required": true,
      "allowed_values": ["Engineering", "Sales", "Marketing", "HR"],
      "created_at": 1705968000
    },
    {
      "key": "clearance_level",
      "display_name": "Security Clearance",
      "description": "Security clearance level",
      "type": "integer",
      "category": "security",
      "required": false,
      "min_value": 1,
      "max_value": 5,
      "default_value": 1,
      "created_at": 1706054400
    }
  ],
  "total": 15
}

Create Attribute Definition

Create a new attribute definition.

Endpoint

POST /api/admin/attributes

Request Body

Field	Type	Required	Description
`key`	string	✓	Attribute key (alphanumeric, underscores)
`display_name`	string	✓	Display name
`description`	string	-	Description
`type`	string	✓	Type (`string`, `integer`, `boolean`, `date`, `array`)
`category`	string	-	Category
`required`	boolean	-	Whether required
`default_value`	any	-	Default value
`allowed_values`	array	-	Allowed values (for enum types)
`min_value`	number	-	Minimum value (for numeric types)
`max_value`	number	-	Maximum value (for numeric types)
`expires_after`	integer	-	Expiration period (seconds)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/attributes" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "certification",
    "display_name": "Certifications",
    "description": "Certifications held",
    "type": "array",
    "category": "qualification",
    "required": false,
    "allowed_values": ["AWS-SAA", "AWS-SAP", "GCP-ACE", "GCP-PCA"]
  }'

Response Example

{
  "key": "certification",
  "display_name": "Certifications",
  "type": "array",
  "category": "qualification",
  "created_at": 1706140800
}

Get User Attributes

Retrieve attributes for a specified user.

Endpoint

GET /api/admin/attributes/users/:userId

Path Parameters

Parameter	Type	Required	Description
`userId`	string	✓	User ID

Request Example

curl -X GET "https://{tenant-domain}/api/admin/attributes/users/usr_abc123" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "user_id": "usr_abc123",
  "attributes": {
    "age_verified": {
      "value": true,
      "verified_at": 1705881600,
      "verified_by": "system",
      "expires_at": null
    },
    "department": {
      "value": "Engineering",
      "set_at": 1705968000,
      "set_by": "usr_admin001"
    },
    "clearance_level": {
      "value": 3,
      "set_at": 1706054400,
      "set_by": "usr_admin001",
      "expires_at": 1737590400
    },
    "certification": {
      "value": ["AWS-SAA", "GCP-ACE"],
      "set_at": 1706140800,
      "set_by": "usr_admin001"
    }
  }
}

Update User Attributes

Update a user’s attributes.

Endpoint

PUT /api/admin/attributes/users/:userId

Path Parameters

Parameter	Type	Required	Description
`userId`	string	✓	User ID

Request Body

Field	Type	Required	Description
`attributes`	object	✓	Map of attribute keys and values

Request Example

curl -X PUT "https://{tenant-domain}/api/admin/attributes/users/usr_abc123" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "clearance_level": 4,
      "certification": ["AWS-SAA", "AWS-SAP", "GCP-ACE"]
    }
  }'

Response Example

{
  "user_id": "usr_abc123",
  "updated_attributes": ["clearance_level", "certification"],
  "updated_at": 1706227200
}

Delete User Attribute

Delete a specific attribute from a user.

Endpoint

DELETE /api/admin/attributes/users/:userId/:key

Path Parameters

Parameter	Type	Required	Description
`userId`	string	✓	User ID
`key`	string	✓	Attribute key

Request Example

curl -X DELETE "https://{tenant-domain}/api/admin/attributes/users/usr_abc123/certification" \
  -H "Authorization: Bearer {token}"

Response

Status code 204 No Content (no body)

List Verification History

Retrieve attribute verification history.

Endpoint

GET /api/admin/attributes/verifications

Query Parameters

Parameter	Type	Required	Description
`limit`	integer	-	Number of items (default: 50)
`cursor`	string	-	Pagination cursor
`user_id`	string	-	Filter by user ID
`attribute_key`	string	-	Filter by attribute key
`result`	string	-	Filter by result (`verified`, `rejected`, `pending`)

Request Example

curl -X GET "https://{tenant-domain}/api/admin/attributes/verifications?attribute_key=age_verified" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "items": [
    {
      "id": "ver_abc123",
      "user_id": "usr_xyz789",
      "attribute_key": "age_verified",
      "result": "verified",
      "method": "document_upload",
      "verified_by": "system",
      "verified_at": 1706140800,
      "evidence": {
        "document_type": "drivers_license",
        "document_id": "doc_xxx"
      }
    }
  ],
  "total": 50,
  "cursor": "eyJpZCI6InZlcl9hYmMxMjMifQ=="
}

Execute Attribute Verification

Manually verify an attribute as an administrator.

Endpoint

POST /api/admin/attributes/verifications

Request Body

Field	Type	Required	Description
`user_id`	string	✓	User ID
`attribute_key`	string	✓	Attribute key
`value`	any	✓	Value to verify
`result`	string	✓	Result (`verified`, `rejected`)
`notes`	string	-	Notes

Request Example

curl -X POST "https://{tenant-domain}/api/admin/attributes/verifications" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_abc123",
    "attribute_key": "age_verified",
    "value": true,
    "result": "verified",
    "notes": "Verified identity documents"
  }'

Response Example

{
  "id": "ver_new789",
  "user_id": "usr_abc123",
  "attribute_key": "age_verified",
  "result": "verified",
  "verified_by": "usr_admin001",
  "verified_at": 1706313600
}

Get Attribute Statistics

Retrieve statistics about attribute usage.

Endpoint

GET /api/admin/attributes/stats

Request Example

curl -X GET "https://{tenant-domain}/api/admin/attributes/stats" \
  -H "Authorization: Bearer {token}"

Response Example

{
  "total_users_with_attributes": 1250,
  "attributes": {
    "age_verified": {
      "users_count": 800,
      "verified_count": 750,
      "pending_count": 50
    },
    "department": {
      "users_count": 1200,
      "distribution": {
        "Engineering": 450,
        "Sales": 300,
        "Marketing": 250,
        "HR": 200
      }
    },
    "clearance_level": {
      "users_count": 500,
      "distribution": {
        "1": 200,
        "2": 150,
        "3": 100,
        "4": 40,
        "5": 10
      }
    }
  },
  "expiring_soon": 25
}

Bulk Delete Expired Attributes

Bulk delete attributes that have expired.

Endpoint

POST /api/admin/attributes/bulk/cleanup-expired

Request Body

Field	Type	Required	Description
`attribute_keys`	string[]	-	Target attribute keys (all if not specified)
`dry_run`	boolean	-	Dry run (don’t actually delete)

Request Example

curl -X POST "https://{tenant-domain}/api/admin/attributes/bulk/cleanup-expired" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "attribute_keys": ["clearance_level"],
    "dry_run": true
  }'

Response Example

{
  "dry_run": true,
  "affected_users": 25,
  "affected_attributes": {
    "clearance_level": 25
  }
}