Manage PrivX roles

get /role-store/api/v1/roles

Get role definitions.

offset

int

Offset where to start fetching the items

Default
0

limit

int

Number of items to return

Default
50
Max
1000

sortkey

string

Sort by specific object property

sortdir

string

Sort direction, asc or desc

Default
"ASC"
Enum
  • ASC
  • DESC

Response

ExamplesSchema

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.

name

string

required

Name of the role

comment

string

A comment describing the object

Example
"A comment"

permit_agent

boolean

Permit agent

access_group_id

string

uuid

Scopes host and connection permissions to an access group

permissions

array[string]

Array of permissions

context

object (context)

Contextual limitation

type

string

role type

arn

string

role ARN

source_rules

object (source_rules)

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[string]

Array of tag strings

source

string

Source of rule

member_count

int

Role member count

Request

{
  "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

ExamplesSchema

Role Successfully created

{
  "id": "5bf77342-221c-11ee-be56-0242ac120002"
}

post /role-store/api/v1/roles/resolve

Resolve role names to role IDs

array[string]

Content Type
application/json

Request

[
  "string"
]

Response

ExamplesSchema

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.

name

array[string]

List of roles names.

Request

{
  "name": [
    "string"
  ]
}

Response

ExamplesSchema

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.

id

string

uuid

The UUID of the returned object

Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"

name

string

required

Name of the role

comment

string

A comment describing the object

Example
"A comment"

principal_public_key_strings

array[string]

permit_agent

boolean

Permit agent

access_group_id

string

uuid

Scopes host and connection permissions to an access group

permissions

array[string]

Array of permissions

context

object (context)

Contextual limitation

type

string

role type

arn

string

role ARN

system

boolean

Is the role PrivX internal

Default
false

created

string

date-time

When the object was created

Example
"2017-01-01T15:05:05Z"

author

string

uuid

ID of the user who originally authored the object

updated

string

date-time

When the object was created

Example
"2017-01-01T15:05:05Z"

updated_by

string

uuid

ID of the user who updated the object

Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"

deleted

string

date-time

When the object was deleted (tombstoned)

Example
"2017-01-01T15:05:05Z"

deleted_by

string

uuid

ID of the user who deleted the object

Example
"eef4aefc-d64e-4c2c-aba4-4914c86ce059"

source_rules

object (source_rules)

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[string]

Array of tag strings

source

string

Source of rule

member_count

int

Role member count

Request

{
  "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

ExamplesSchema

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_id

string

required

Role ID

Response

ExamplesSchema

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.

name

string

required

Name of the role

comment

string

A comment describing the object

Example
"A comment"

permit_agent

boolean

Permit agent

access_group_id

string

uuid

Scopes host and connection permissions to an access group

permissions

array[string]

Array of permissions

context

object (context)

Contextual limitation

type

string

role type

arn

string

role ARN

source_rules

object (source_rules)

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[string]

Array of tag strings

source

string

Source of rule

member_count

int

Role member count

Request

{
  "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

ExamplesSchema

Role successfully updated

Empty response