• Role Store

role

Manage PrivX roles

get/role-store/api/v1/roles

Get role definitions.

offsetint

Offset where to start fetching the items

Default
0
limitint

Number of items to return

Default
50
Max
1000
sortkeystring

Sort by specific object property

sortdirstring

Sort direction, asc or desc

Default
"ASC"
Enum
  • ASC
  • DESC

Responses

Response examples

Successful response, returns an object with roles and count.

{
  "count": 123,
  "items": [
    {
      "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "name": "string",
      "comment": "A comment",
      "principal_public_key_strings": [
        "string"
      ],
      "permit_agent": true,
      "access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
      "permissions": [
        "licenses-manage"
      ],
      "context": {
        "enabled": true,
        "block_role": true,
        "validity": [
          "MON"
        ],
        "start_time": "string",
        "end_time": "string",
        "timezone": "string",
        "ip_masks": [
          "string"
        ]
      },
      "type": "string",
      "arn": "string",
      "system": true,
      "created": "2017-01-01T15:05:05Z",
      "author": "5bf77342-221c-11ee-be56-0242ac120002",
      "updated": "2017-01-01T15:05:05Z",
      "updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "deleted": "2017-01-01T15:05:05Z",
      "deleted_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "source_rules": {
        "type": "RULE",
        "source": "string",
        "search_string": "string",
        "match": "ALL",
        "rules": [
          null
        ]
      },
      "tags": [
        "string"
      ],
      "source": "string",
      "member_count": 123
    }
  ]
}
post/role-store/api/v1/roles

Create a new role definition. ID, author, created & updated fields are automatically populated by the server.

namestring

required

Name of the role

commentstring

A comment describing the object

Example
"A comment"
permit_agentboolean

Permit agent

access_group_idstring

Scopes host and connection permissions to an access group

Format
uuid
permissionsarray

Array of permissions

contextobject (contextual_limitation)

Contextual limitation

enabledboolean

Are contextual limitations enabled

block_roleboolean

If set to true and contextual limitations do not allow role/object, then the role/object is blocked. Otherwise the role/object is granted and an audit event is triggered.

validityarray
start_timestring

Start time of day as HH:MM when contextual limit allows access

end_timestring

End time of day as HH:MM when contextual limit allows access

timezonestring

Time zone of start_time and end_time

ip_masksarray
typestring

role type

arnstring

role ARN

source_rulesobject (source_rule)

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

typestring

Is the source rule a single rule or a group

Enum
  • RULE
  • GROUP
sourcestring

For single type, the ID of the source provider

search_stringstring

For single type, the search string at the source provider.

matchstring

For group type, should all or any of the rules in the rules array match

Enum
  • ALL
  • ANY
rulesarray

For group type, the rules array

tagsarray

Array of tag strings

sourcestring

Source of rule

member_countint

Role member count

Responses

Request examples

{
  "name": "string",
  "comment": "A comment",
  "permit_agent": true,
  "access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
  "permissions": [
    "licenses-manage"
  ],
  "context": {
    "enabled": true,
    "block_role": true,
    "validity": [
      "MON"
    ],
    "start_time": "string",
    "end_time": "string",
    "timezone": "string",
    "ip_masks": [
      "string"
    ]
  },
  "type": "string",
  "arn": "string",
  "source_rules": {
    "type": "RULE",
    "source": "string",
    "search_string": "string",
    "match": "ALL",
    "rules": [
      null
    ]
  },
  "tags": [
    "string"
  ],
  "source": "string",
  "member_count": 123
}

Response examples

Role Successfully created

{
  "id": "5bf77342-221c-11ee-be56-0242ac120002"
}
post/role-store/api/v1/roles/resolve

Resolve role names to role IDs

Array of strings

Responses

Request examples

[
  "string"
]

Response examples

Roles found, role IDs returned

{
  "count": 123,
  "items": [
    {
      "id": "5bf77342-221c-11ee-be56-0242ac120002",
      "role_name": "string"
    }
  ]
}
post/role-store/api/v1/roles/search

Search roles with role search parameters.

namearray

List of roles names.

Responses

Request examples

{
  "name": [
    "string"
  ]
}

Response examples

Successful response, returns a list of roles

{
  "count": 123,
  "items": [
    {
      "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "name": "string",
      "type": "string",
      "member_count": 123
    }
  ]
}
post/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.

idstring

The UUID of the returned object

Format
uuid
Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"
namestring

required

Name of the role

commentstring

A comment describing the object

Example
"A comment"
principal_public_key_stringsarray
permit_agentboolean

Permit agent

access_group_idstring

Scopes host and connection permissions to an access group

Format
uuid
permissionsarray

Array of permissions

contextobject (contextual_limitation)

Contextual limitation

enabledboolean

Are contextual limitations enabled

block_roleboolean

If set to true and contextual limitations do not allow role/object, then the role/object is blocked. Otherwise the role/object is granted and an audit event is triggered.

validityarray
start_timestring

Start time of day as HH:MM when contextual limit allows access

end_timestring

End time of day as HH:MM when contextual limit allows access

timezonestring

Time zone of start_time and end_time

ip_masksarray
typestring

role type

arnstring

role ARN

systemboolean

Is the role PrivX internal

Default
false
createdstring

When the object was created

Format
date-time
Example
"2017-01-01T15:05:05Z"
authorstring

ID of the user who originally authored the object

Format
uuid
updatedstring

When the object was created

Format
date-time
Example
"2017-01-01T15:05:05Z"
updated_bystring

ID of the user who updated the object

Format
uuid
Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"
deletedstring

When the object was deleted (tombstoned)

Format
date-time
Example
"2017-01-01T15:05:05Z"
deleted_bystring

ID of the user who deleted the object

Format
uuid
Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"
source_rulesobject (source_rule)

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

typestring

Is the source rule a single rule or a group

Enum
  • RULE
  • GROUP
sourcestring

For single type, the ID of the source provider

search_stringstring

For single type, the search string at the source provider.

matchstring

For group type, should all or any of the rules in the rules array match

Enum
  • ALL
  • ANY
rulesarray

For group type, the rules array

tagsarray

Array of tag strings

sourcestring

Source of rule

member_countint

Role member count

Responses

Request examples

{
  "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "name": "string",
  "comment": "A comment",
  "principal_public_key_strings": [
    "string"
  ],
  "permit_agent": true,
  "access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
  "permissions": [
    "licenses-manage"
  ],
  "context": {
    "enabled": true,
    "block_role": true,
    "validity": [
      "MON"
    ],
    "start_time": "string",
    "end_time": "string",
    "timezone": "string",
    "ip_masks": [
      "string"
    ]
  },
  "type": "string",
  "arn": "string",
  "system": true,
  "created": "2017-01-01T15:05:05Z",
  "author": "5bf77342-221c-11ee-be56-0242ac120002",
  "updated": "2017-01-01T15:05:05Z",
  "updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "deleted": "2017-01-01T15:05:05Z",
  "deleted_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "source_rules": {
    "type": "RULE",
    "source": "string",
    "search_string": "string",
    "match": "ALL",
    "rules": [
      null
    ]
  },
  "tags": [
    "string"
  ],
  "source": "string",
  "member_count": 123
}

Response examples

Response for role mapping evaluation

{
  "count": 123,
  "items": [
    {
      "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "source_user_id": null,
      "created": "2017-01-01T15:05:05Z",
      "updated": "2017-01-01T15:05:05Z",
      "updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "author": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "comment": "A comment",
      "tags": [
        "string"
      ],
      "principal": "string",
      "distinguished_name": "string",
      "given_name": "string",
      "full_name": "string",
      "job_title": "string",
      "company": "string",
      "department": "string",
      "email": "string",
      "telephone": "string",
      "locale": "fi_FI",
      "roles": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "string",
          "comment": "A comment",
          "principal_public_key_strings": [
            "string"
          ],
          "permit_agent": true,
          "access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
          "permissions": [
            "licenses-manage"
          ],
          "context": {
            "enabled": true,
            "block_role": true,
            "validity": [
              "MON"
            ],
            "start_time": "string",
            "end_time": "string",
            "timezone": "string",
            "ip_masks": [
              "string"
            ]
          },
          "explicit": true,
          "implicit": true,
          "system": true,
          "grant_type": "PERMANENT",
          "grant_validity_periods": [
            {
              "grant_start": "2017-01-01T15:05:05Z",
              "grant_end": "2017-01-02T15:05:05Z"
            }
          ],
          "floating_length": 24
        }
      ],
      "attributes": [
        {
          "key": "aws_account",
          "value": "admin-bob"
        }
      ],
      "permissions": [
        "licenses-manage"
      ],
      "source": "string",
      "mfa": {
        "status": "ENABLED",
        "seed": {
          "seed_string": "string",
          "seed_qr_code": "string"
        }
      },
      "stale_access_token": true,
      "authorized_keys": [
        {
          "id": "2765b005-4ce1-4b2b-a9ca-ee6c4d6f2792",
          "username": "joe@privx.com",
          "user_id": "f2f448d8-0397-4894-982f-9a58a43921db",
          "source": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "work",
          "comment": "Joe's work laptop key",
          "public_key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDqoMogqErOw7lL3GD6Ez7Hv1FZBk0Iyk2pBFUhqb9sjY9IEw8P9OWFwLMhWQ4LNvekPAnmr03pMHSSP7Pw98+Izy0HxcHZGKcrDOIjnHF5Fog3w4rBYa6OxdcJRxctifx5szqmM4JkUNS1RJY5E4ns4xCgFV46Satph02M+eP9PXGh+ZecSNtdLoOovVuolEUdb8dINgto8zsjEuAQ+76qOEgAIuSsYlzGGZPyPnATtkUi/rK9fcAfbhSqSXNxFqf7wejEKwA1kFt8hSW2bUWJH268fqnejFwHjBTzjBw89dji6141ajAP8/Q2gZug0bb1U70PE4afE3fFh2VCfhwT",
          "not_before": "2020-07-31T17:32:28Z",
          "not_after": "2022-07-31T17:32:28Z",
          "expires_in": 123,
          "source_address": [
            "192.168.100.0/24"
          ],
          "fingerprints": [
            "SHA256:bdeYZ2qiEwCOCuf0oTvya/aH4Vo+nJLIauDKm/D8btM"
          ]
        }
      ],
      "webauthn_credentials": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "credential_id": "string",
          "name": "string",
          "comment": "string",
          "last_used": "2017-01-01T15:05:05Z",
          "created": "2017-01-01T15:05:05Z",
          "author": "5bf77342-221c-11ee-be56-0242ac120002",
          "updated": "2017-01-01T15:05:05Z",
          "updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059"
        }
      ]
    }
  ]
}
get/role-store/api/v1/roles/{role_id}

Get role object by ID.

role_idstring

required

Role ID

Responses

Response examples

Successful response, returns a role if found

{
  "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "name": "string",
  "comment": "A comment",
  "principal_public_key_strings": [
    "string"
  ],
  "permit_agent": true,
  "access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
  "permissions": [
    "licenses-manage"
  ],
  "context": {
    "enabled": true,
    "block_role": true,
    "validity": [
      "MON"
    ],
    "start_time": "string",
    "end_time": "string",
    "timezone": "string",
    "ip_masks": [
      "string"
    ]
  },
  "type": "string",
  "arn": "string",
  "system": true,
  "created": "2017-01-01T15:05:05Z",
  "author": "5bf77342-221c-11ee-be56-0242ac120002",
  "updated": "2017-01-01T15:05:05Z",
  "updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "deleted": "2017-01-01T15:05:05Z",
  "deleted_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
  "source_rules": {
    "type": "RULE",
    "source": "string",
    "search_string": "string",
    "match": "ALL",
    "rules": [
      null
    ]
  },
  "tags": [
    "string"
  ],
  "source": "string",
  "member_count": 123
}
put/role-store/api/v1/roles/{role_id}

Update a role.

namestring

required

Name of the role

commentstring

A comment describing the object

Example
"A comment"
permit_agentboolean

Permit agent

access_group_idstring

Scopes host and connection permissions to an access group

Format
uuid
permissionsarray

Array of permissions

contextobject (contextual_limitation)

Contextual limitation

enabledboolean

Are contextual limitations enabled

block_roleboolean

If set to true and contextual limitations do not allow role/object, then the role/object is blocked. Otherwise the role/object is granted and an audit event is triggered.

validityarray
start_timestring

Start time of day as HH:MM when contextual limit allows access

end_timestring

End time of day as HH:MM when contextual limit allows access

timezonestring

Time zone of start_time and end_time

ip_masksarray
typestring

role type

arnstring

role ARN

source_rulesobject (source_rule)

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

typestring

Is the source rule a single rule or a group

Enum
  • RULE
  • GROUP
sourcestring

For single type, the ID of the source provider

search_stringstring

For single type, the search string at the source provider.

matchstring

For group type, should all or any of the rules in the rules array match

Enum
  • ALL
  • ANY
rulesarray

For group type, the rules array

tagsarray

Array of tag strings

sourcestring

Source of rule

member_countint

Role member count

Responses

Request examples

{
  "name": "string",
  "comment": "A comment",
  "permit_agent": true,
  "access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
  "permissions": [
    "licenses-manage"
  ],
  "context": {
    "enabled": true,
    "block_role": true,
    "validity": [
      "MON"
    ],
    "start_time": "string",
    "end_time": "string",
    "timezone": "string",
    "ip_masks": [
      "string"
    ]
  },
  "type": "string",
  "arn": "string",
  "source_rules": {
    "type": "RULE",
    "source": "string",
    "search_string": "string",
    "match": "ALL",
    "rules": [
      null
    ]
  },
  "tags": [
    "string"
  ],
  "source": "string",
  "member_count": 123
}

Response examples

Role successfully updated

Empty response

delete/role-store/api/v1/roles/{role_id}

Delete role by ID.

role_idstring

required

Role ID

Responses

Response examples

Role Successfully deleted

Empty response

get/role-store/api/v1/roles/{role_id}/members

Get role members by role ID.

offsetint

Offset where to start fetching the items

Default
0
limitint

Number of items to return

Default
50
Max
100
sortkeystring

Sort by specific object property

sortdirstring

Sort direction, asc or desc

Default
"ASC"
Enum
  • ASC
  • DESC

Responses

Response examples

Successful response

{
  "count": 123,
  "items": [
    {
      "id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "source_user_id": null,
      "created": "2017-01-01T15:05:05Z",
      "updated": "2017-01-01T15:05:05Z",
      "updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "author": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
      "comment": "A comment",
      "tags": [
        "string"
      ],
      "principal": "string",
      "distinguished_name": "string",
      "given_name": "string",
      "full_name": "string",
      "job_title": "string",
      "company": "string",
      "department": "string",
      "email": "string",
      "telephone": "string",
      "locale": "fi_FI",
      "roles": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "string",
          "comment": "A comment",
          "principal_public_key_strings": [
            "string"
          ],
          "permit_agent": true,
          "access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
          "permissions": [
            "licenses-manage"
          ],
          "context": {
            "enabled": true,
            "block_role": true,
            "validity": [
              "MON"
            ],
            "start_time": "string",
            "end_time": "string",
            "timezone": "string",
            "ip_masks": [
              "string"
            ]
          },
          "explicit": true,
          "implicit": true,
          "system": true,
          "grant_type": "PERMANENT",
          "grant_validity_periods": [
            {
              "grant_start": "2017-01-01T15:05:05Z",
              "grant_end": "2017-01-02T15:05:05Z"
            }
          ],
          "floating_length": 24
        }
      ],
      "attributes": [
        {
          "key": "aws_account",
          "value": "admin-bob"
        }
      ],
      "permissions": [
        "licenses-manage"
      ],
      "source": "string",
      "mfa": {
        "status": "ENABLED",
        "seed": {
          "seed_string": "string",
          "seed_qr_code": "string"
        }
      },
      "stale_access_token": true,
      "authorized_keys": [
        {
          "id": "2765b005-4ce1-4b2b-a9ca-ee6c4d6f2792",
          "username": "joe@privx.com",
          "user_id": "f2f448d8-0397-4894-982f-9a58a43921db",
          "source": "5bf77342-221c-11ee-be56-0242ac120002",
          "name": "work",
          "comment": "Joe's work laptop key",
          "public_key": "AAAAB3NzaC1yc2EAAAADAQABAAABAQDqoMogqErOw7lL3GD6Ez7Hv1FZBk0Iyk2pBFUhqb9sjY9IEw8P9OWFwLMhWQ4LNvekPAnmr03pMHSSP7Pw98+Izy0HxcHZGKcrDOIjnHF5Fog3w4rBYa6OxdcJRxctifx5szqmM4JkUNS1RJY5E4ns4xCgFV46Satph02M+eP9PXGh+ZecSNtdLoOovVuolEUdb8dINgto8zsjEuAQ+76qOEgAIuSsYlzGGZPyPnATtkUi/rK9fcAfbhSqSXNxFqf7wejEKwA1kFt8hSW2bUWJH268fqnejFwHjBTzjBw89dji6141ajAP8/Q2gZug0bb1U70PE4afE3fFh2VCfhwT",
          "not_before": "2020-07-31T17:32:28Z",
          "not_after": "2022-07-31T17:32:28Z",
          "expires_in": 123,
          "source_address": [
            "192.168.100.0/24"
          ],
          "fingerprints": [
            "SHA256:bdeYZ2qiEwCOCuf0oTvya/aH4Vo+nJLIauDKm/D8btM"
          ]
        }
      ],
      "webauthn_credentials": [
        {
          "id": "5bf77342-221c-11ee-be56-0242ac120002",
          "credential_id": "string",
          "name": "string",
          "comment": "string",
          "last_used": "2017-01-01T15:05:05Z",
          "created": "2017-01-01T15:05:05Z",
          "author": "5bf77342-221c-11ee-be56-0242ac120002",
          "updated": "2017-01-01T15:05:05Z",
          "updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059"
        }
      ]
    }
  ]
}
get/role-store/api/v1/roles/{role_id}/awstoken

Get an AWS token for the role. Return 403 on an initial request if the AWS role has multi-factor authentication enabled. Subsequent request must contain MFA as a query parameter. Return 403 if the user does not have the role.

tokencodestring

Multi-factor-authentication code

ttlint

Max time validity for the token. Default used if not provided.

Responses

Response examples

Successful response

{
  "access_key_id": "ASXXXXXXXXXXXXXXXXZZ",
  "secret_access_key": "GXXXXxxxxxXXXXxXXXXXxXXxXxxxxXxXXXXXXO",
  "session_token": "VrBAxpy9IeCQfjz2bgGIklLYZfkYfznRHA7hgpkP9ipw8n7GBCExYPHcL4DEngun21vHiIYqMteXaEVGc38wHakrLUOJcgDm5BjyEZpKIW6JLshmM67ZXkyP3nIhdL5szCY3IJWlIh9Gh72Z1UTaX3XdlDnxmkeEmjZzl34CgXBnY7hGTvBxw09ocJ7aSyZ2RtQmdqvRDhw6SATwZmrvFlRFK6cMiAgxUYnTMBZInd3b9quWjdBAIJKgwVzeA5CioVqn8qnsOStM7cqMxmRMc3UpfByOmqNAhXTrywfSMOYftU4NLkGchlRBw0v1UmBch1v4alvoyjtqtPcPI3BXjagdBpqnZrobGgnWOAVZrOsA27k21CnNmjHhnRqrNk0EKIfxsBLfTVSjc3DRle2jbs7lT96OedMEApCCk71zZRUzKb2SHmeQEJBDpIKspEVPKmuTfqI1Z6vgdPu0mBpYB4nBWzY1lTbuDXfMKoQXhYbnM2PQ41pgfk0BZubWsuODMWC190CQgwaDlrWDzEyoQ63EkF4x",
  "expires": "2017-03-09T22:30:26Z",
  "descriptions": [
    "Policy x to access y"
  ]
}
get/role-store/api/v1/roles/{role_id}/principalkeys

Get role's principal key objects.

role_idstring

required

Role ID

Responses

Response examples

Successful response, returns a role if found

{
  "count": 123,
  "items": [
    {
      "id": "5bf77342-221c-11ee-be56-0242ac120002",
      "public_key": "string"
    }
  ]
}
post/role-store/api/v1/roles/{role_id}/principalkeys/generate

Generate new principal key for role.

role_idstring

required

Role ID

Responses

Response examples

Successful response, returns the role principal key id

{
  "id": "string"
}
post/role-store/api/v1/roles/{role_id}/principalkeys/import

Import new principal key for role.

private_keystring

PEM encoded private key, pkcs#8, RSA, ECDSA and Ed25519 private keys are supported

Responses

Request examples

{
  "private_key": "string"
}

Response examples

Successful response, returns the role principal key id

{
  "id": "string"
}
get/role-store/api/v1/roles/{role_id}/principalkeys/{key_id}

Get role's principal key object.

role_idstring

required

Role ID

key_idstring

required

Principal key ID

Responses

Response examples

Successful response

{
  "id": "5bf77342-221c-11ee-be56-0242ac120002",
  "public_key": "string"
}
delete/role-store/api/v1/roles/{role_id}/principalkeys/{key_id}

Delete a role's principal key object.

role_idstring

required

Role ID

key_idstring

required

Principal key ID

Responses

Response examples

Successful response

Empty response

Was this page helpful?