/role-store/api/v1/roles/evaluate

post https://example.com/role-store/api/v1/roles/evaluate

Evaluate a new role definition. Returns an array of matching users for the role mapping. If too many hits, only count field is populated and users array is left empty.

Body Params

uuid

The UUID of the returned object

name

string

required

Name of the role

comment

string

A comment describing the object

principal_public_key_strings

array of strings

principal_public_key_strings

permit_agent

boolean

Permit agent

access_group_id

uuid

Scopes host and connection permissions to an access group

permissions

array of strings

Array of permissions

permissions

context

object

Contextual limitation

type

string

role type

arn

string

role ARN

system

boolean

Defaults to false

Is the role PrivX internal

created

date-time

When the object was created

author

uuid

ID of the user who originally authored the object

updated

date-time

When the object was created

updated_by

uuid

ID of the user who updated the object

deleted

date-time

When the object was deleted (tombstoned)

deleted_by

uuid

ID of the user who deleted the object

source_rules

object

required

A source rule(s) definition. Can be a single rule or a rule group, in which case either "single" or "group" attributes are requrired

tags

array of strings

Array of tag strings

tags

source

string

Source of rule

member_count

integer

Role member count

Headers

Authorization

string

required

Defaults to Bearer a-proper-token-goes-here

OAuth2 token

Responses

Response body

object

count

integer

items

array of objects

items

object

uuid

The UUID of the returned object

source_user_id

string

The originating unique identifer for the user (UUID from local user store, principal from LDAP, ..) - only returned by the Role Store API

created

date-time

When the object was created

updated

date-time

When the object was created

updated_by

uuid

ID of the user who updated the object

author

uuid

ID of the user who originally authored the object

comment

string

A comment describing the object

tags

array of strings

Array of tag strings

tags

principal

string

The principal name of the user. For IAM Local User Store users, the username.

distinguished_name

string

The distinguished name of the user

given_name

string

First name

full_name

string

Full name

job_title

string

Job title

company

string

Company

department

string

Department

string

Email address

telephone

string

Phone number

locale

string

User's locale. Language code ISO 639-1 & country code ISO 3166-1 separated by a "_"

roles

array of objects

The array of role IDs the user has. Boolean "explicit" denotes whether the role is granted explicitly or implicitly via a mapping.

roles

object

uuid

name

string

comment

string

A comment describing the object

principal_public_key_strings

array of strings

Principal public keys, returned only from /users/resolve

principal_public_key_strings

permit_agent

boolean

Permit agent, returned only from /users/resolve

access_group_id

uuid

Scopes host and connection permissions to an access group

permissions

array of strings

Array of permissions

permissions

context

object

Contextual limitation

explicit

boolean

Defaults to false

Is the role explicitly granted to the user

implicit

boolean

Defaults to false

Has the user implicitly gained the role or not.

system

boolean

Defaults to false

grant_type

string

Is the role granted permanently, or is the grant time restricted, or a floating window. The floating window starts upon initial connection at which time the Role Store converts the floating window to explicit time-restricted window.

PERMANENT TIME_RESTRICTED FLOATING

grant_validity_periods

array of objects

Array of validity periods for this role. This array replaces grant_start and grant_end attributes in role object.

grant_validity_periods

object

grant_start

date-time

Date & time after which the role is granted to the user in ISO8601

grant_end

date-time

Date & time after which the role is removed from the user in ISO8601

floating_length

integer

Duration for which the grant should last after initial connection, specified in hours

attributes

array of objects

Custom user attributes array.

attributes

object

key

string

required

value

string

required

permissions

array of strings

Array of permissions

permissions

source

string

Source ID

mfa

object

stale_access_token

boolean

The access token used for fetching the user object has permissions that are out of sync. The requester should refresh the access token before the next REST API call. This field is set only by /users/current endpoint.

authorized_keys

array of objects

authorized_keys

object

uuid

Unique identifier for authorized key

username

string

Username of the authorized key owner

user_id

uuid

User id of the authorized key owner

source

uuid

User source ID

name

string

required

Name for authorized key

comment

string

Comment for authorized key

public_key

string

Public key data in ssh authorized key format

not_before

date-time

Start of key validity period

not_after

date-time

End of key validity period

expires_in

integer

Time in seconds to key expiry. Value is not set if key is not yet valid.

source_address

array of strings

source_address

fingerprints

array of strings

fingerprints

webauthn_credentials

array of objects

webauthn_credentials

object

uuid

required

Credential UUID

credential_id

string

Webauthn credential ID

name

string

Credential name

comment

string

Optional comment

last_used

date-time

Timestamp of last login event using this credential

created

date-time

Creation timestamp

author

uuid

ID of the user who originally authored the object

updated

date-time

Update timestamp

updated_by

uuid

ID of the user who updated the object

Language

Credentials

OAuth2


xxxxxxxxxx
1
curl --request POST \
2
     --url https://example.com/role-store/api/v1/roles/evaluate \
3
     --header 'Authorization: Bearer a-proper-token-goes-here' \
4
     --header 'accept: application/json' \
5
     --header 'content-type: application/json' \
6
     --data '{"system":false}'

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Response for role mapping evaluation

400Bad request

401Unauthorized request, OAuth2 authorization missing or invalid

403Unauthorized request, OAuth2 authorization OK but scope insufficient

404Resource not found

500Internal server error