# IAM Administration and Audit

## Added APIs

- `GET /api/v1/iam/permissions`
- `GET /api/v1/iam/roles`
- `POST /api/v1/iam/roles`
- `POST /api/v1/iam/memberships/{membershipPublicId}/roles`

## Security

Every route remains behind:

1. Sanctum authentication
2. tenant resolution
3. active tenant membership
4. explicit permission middleware

The administration permissions are separate from normal business permissions.

## Scoped assignments

Role assignments can be stored at:

- tenant scope
- company scope
- branch scope

All referenced scope entities must belong to the active tenant.
Cross-tenant membership, role, company, or branch references are rejected.

## Audit

Sensitive IAM mutations write immutable audit events.

Current event types:

- `iam.role.created`
- `iam.role.assigned`

Audit records capture actor, tenant, subject, timestamp, before/after payloads
where applicable, request IP, and user agent.

Audit records are append-only at the application layer.

## Next

The next increment should add:

- role update / permission rule replacement
- role assignment removal/revocation
- membership administration
- scoped permission checks on business routes using company/branch context
- audit query API with strict permission protection