KMP PHP API Reference

ServicePrincipal extends BaseEntity
in package
implements KmpIdentityInterface, IdentityInterface, IdentityInterface

ServicePrincipal Entity - API Client Identity for Third-Party Integrations

Implements authentication and authorization for API clients. Works like Member but for service-to-service integrations.

Table of Contents

Interfaces

KmpIdentityInterface
IdentityInterface
IdentityInterface

Properties

$branch_id  : int|null
$client_id  : string
$client_secret_hash  : string
$created  : DateTime
$created_by  : int|null
$description  : string|null
$id  : int
$ip_allowlist  : array<string|int, mixed>|null
$is_active  : bool
$last_used_at  : DateTime|null
$modified  : DateTime
$modified_by  : int|null
$name  : string
$service_principal_roles  : array<string|int, ServicePrincipalRole>
$service_principal_tokens  : array<string|int, ServicePrincipalToken>
$_accessible  : array<string, bool>
Fields accessible for mass assignment.
$_hidden  : array<string|int, string>
$_permissions  : array<string|int, mixed>|null
$authorization  : AuthorizationServiceInterface|null

Methods

applyScope()  : mixed
Apply authorization scope.
can()  : bool
Check if service principal can perform action on resource.
canResult()  : ResultInterface
Get detailed authorization result.
checkCan()  : bool
Check authorization, throw ForbiddenException if denied.
generateClientId()  : string
Generate a new client ID with recognizable prefix.
generateClientSecret()  : string
Generate a new client secret (plain text - hash before storing).
getAsMember()  : Member
Return a "member" representation - for service principals, return null.
getBranchId()  : int|null
Get the branch ID for authorization checks.
getIdentifier()  : array<string|int, mixed>|string|int|null
Get the identity identifier.
getOriginalData()  : ArrayAccess|array<string|int, mixed>
Get the decorated identity.
getPermissionIDs()  : array<string|int, int>
Get permission IDs for efficient permission checking.
getPermissions()  : array<string|int, Permission>
Get permissions for this service principal based on assigned roles.
getPolicies()  : array<string|int, mixed>
Get policies for this service principal.
hashSecret()  : string
Hash a client secret for storage.
isIpAllowed()  : bool
Check if an IP address is allowed for this service principal.
isServicePrincipal()  : bool
Check if service principal is a service principal (always true).
isSuperUser()  : bool
Check if service principal has super user privileges.
setAuthorization()  : self
Set the authorization service.
verifySecret()  : bool
Verify a client secret against stored hash.
_getDisplayName()  : string
Get display name for audit logs.
ipMatches()  : bool
Check if IP matches an allowlist entry (supports CIDR notation).

Properties

$branch_id

public int|null $branch_id

Associated branch ID (when applicable)

$_accessible

Fields accessible for mass assignment.

protected array<string, bool> $_accessible = ['name' => true, 'description' => true, 'is_active' => true, 'ip_allowlist' => true, 'last_used_at' => true, 'modified' => true]

$_hidden

protected array<string|int, string> $_hidden = ['client_secret_hash']

Fields hidden from serialization

$_permissions

protected array<string|int, mixed>|null $_permissions = null

Cached permissions

$authorization

protected AuthorizationServiceInterface|null $authorization = null

Methods

applyScope()

Apply authorization scope.

public applyScope(string $action, mixed $resource, mixed ...$optionalArgs) : mixed
Parameters
$action : string

The action

$resource : mixed

The resource

$optionalArgs : mixed

Additional args

can()

Check if service principal can perform action on resource.

public can(string $action, mixed $resource, mixed ...$optionalArgs) : bool
Parameters
$action : string

The action

$resource : mixed

The resource

$optionalArgs : mixed

Additional args

Return values
bool

canResult()

Get detailed authorization result.

public canResult(string $action, mixed $resource, mixed ...$optionalArgs) : ResultInterface
Parameters
$action : string

The action

$resource : mixed

The resource

$optionalArgs : mixed

Additional args

Return values
ResultInterface

checkCan()

Check authorization, throw ForbiddenException if denied.

public checkCan(string $action, mixed $resource, mixed ...$optionalArgs) : bool
Parameters
$action : string

The action

$resource : mixed

The resource

$optionalArgs : mixed

Additional args

Return values
bool

generateClientId()

Generate a new client ID with recognizable prefix.

public static generateClientId() : string
Return values
string —

Client ID in format kmp_sp_XXXX...

generateClientSecret()

Generate a new client secret (plain text - hash before storing).

public static generateClientSecret() : string
Return values
string —

64-byte base64-encoded secret

getAsMember()

Return a "member" representation - for service principals, return null.

public getAsMember() : Member

This signals to systems that this is not a human member.

Return values
Member

getBranchId()

Get the branch ID for authorization checks.

public getBranchId() : int|null

Child classes should override for complex branch relationships.

Return values
int|null —

The branch ID, or null if no association

getIdentifier()

Get the identity identifier.

public getIdentifier() : array<string|int, mixed>|string|int|null
Return values
array<string|int, mixed>|string|int|null

getOriginalData()

Get the decorated identity.

public getOriginalData() : ArrayAccess|array<string|int, mixed>
Return values
ArrayAccess|array<string|int, mixed>

getPermissionIDs()

Get permission IDs for efficient permission checking.

public getPermissionIDs() : array<string|int, int>
Return values
array<string|int, int>

getPermissions()

Get permissions for this service principal based on assigned roles.

public getPermissions() : array<string|int, Permission>
Return values
array<string|int, Permission>

getPolicies()

Get policies for this service principal.

public getPolicies([array<string|int, mixed>|null $branchIds = null ]) : array<string|int, mixed>
Parameters
$branchIds : array<string|int, mixed>|null = null

Optional branch filter

Return values
array<string|int, mixed>

hashSecret()

Hash a client secret for storage.

public static hashSecret(string $secret) : string
Parameters
$secret : string

Plain text secret

Return values
string —

Hashed secret

isIpAllowed()

Check if an IP address is allowed for this service principal.

public isIpAllowed(string $ipAddress) : bool
Parameters
$ipAddress : string

IP address to check

Return values
bool —

True if allowed (or no restrictions set)

isServicePrincipal()

Check if service principal is a service principal (always true).

public isServicePrincipal() : bool
Return values
bool

isSuperUser()

Check if service principal has super user privileges.

public isSuperUser() : bool
Return values
bool

setAuthorization()

Set the authorization service.

public setAuthorization(AuthorizationServiceInterface $service) : self
Parameters
$service : AuthorizationServiceInterface
Return values
self

verifySecret()

Verify a client secret against stored hash.

public verifySecret(string $secret) : bool
Parameters
$secret : string

Plain text secret to verify

Return values
bool —

True if secret matches

_getDisplayName()

Get display name for audit logs.

protected _getDisplayName() : string
Return values
string

ipMatches()

Check if IP matches an allowlist entry (supports CIDR notation).

protected ipMatches(string $ip, string $allowed) : bool
Parameters
$ip : string

IP to check

$allowed : string

Allowed IP or CIDR range

Return values
bool 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results