role

Download Spec

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

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]

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.

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

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

Response

ExamplesSchema

Role successfully updated

Empty response

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

Delete role by ID.

role_id

string

required

Role ID

Response

ExamplesSchema

Role Successfully deleted

Empty response

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

Get role members by role ID.

offset

int

Offset where to start fetching the items

Default
0

limit

int

Number of items to return

Default
50
Max
100

sortkey

string

Sort by specific object property

sortdir

string

Sort direction, asc or desc

Default
"ASC"
Enum
  • ASC
  • DESC

Response

ExamplesSchema

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.

tokencode

string

Multi-factor-authentication code

ttl

int

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

Response

ExamplesSchema

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_id

string

required

Role ID

Response

ExamplesSchema

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_id

string

required

Role ID

Response

ExamplesSchema

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_key

string

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

Response

ExamplesSchema

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_id

string

required

Role ID

key_id

string

required

Principal key ID

Response

ExamplesSchema

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_id

string

required

Role ID

key_id

string

required

Principal key ID

Response

ExamplesSchema

Successful response

Empty response

Was this page helpful?