role
Download SpecManage PrivX roles
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
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
OAuth2
Required Scopes:
user
admin
rolesView
service
Get role definitions.
All Scopes
-
admin
· Admin scope - used for built-in PrivX admin account -
apiClient
· API Client scope - used for scripted access -
authorizedKeysManage
· Client with authorizedkeys-manage -
hostsProvisioning
· Deploy script -
roleTargetResourcesManage
· Client with role-target-resources-manage -
roleTargetResourcesView
· Client with role-target-resources-view -
rolesManage
· Client with roles-manage scope -
rolesView
· Client with roles-view scope -
service
· Microservice scope - used for communication between PrivX microservices -
sourcesManage
· Client with sources-manage scope -
sourcesView
· Client with source-view scope -
user
· Normal users -
usersManage
· Client with users-manage scope -
usersView
· Client with users-view scope
- Flow Type:
- authorization_code
- Auth URL:
- https://api.privx.ssh.com/v1/auth/auth
- Token URL:
- https://api.privx.ssh.com/v1/auth/auth
Response
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
}
]
}
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Bad request
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization missing or invalid
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization OK but scope insufficient
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Resource not found
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Internal server error
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
error_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursivecount
int
items
array[object]
object
A role definition
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]
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
string
- Enum
-
- licenses-manage
- api-clients-manage
- connections-view
- connections-playback
- connections-terminate
- connections-manual
- connections-trail
- hosts-view
- hosts-manage
- privx-host-provisioning
- role-target-resources-view
- role-target-resources-manage
- roles-view
- roles-manage
- sources-view
- sources-manage
- users-view
- users-manage
- logs-view
- logs-manage
- workflows-manage
- workflows-view
- vault-manage
- vault-add
- access-groups-manage
context
object (context)
Contextual limitation
enabled
boolean
Are contextual limitations enabled
block_role
boolean
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.
validity
array[string]
string
Week day on which contextual limitation allows access
- Enum
-
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
start_time
string
Start time of day as HH:MM when contextual limit allows access
end_time
string
End time of day as HH:MM when contextual limit allows access
timezone
string
Time zone of start_time and end_time
ip_masks
array[string]
string
CIDR or IP address where client is connecting from
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
type
string
Is the source rule a single rule or a group
- Enum
-
- RULE
- GROUP
source
string
For single type, the ID of the source provider
search_string
string
For single type, the search string at the source provider.
match
string
For group type, should all or any of the rules in the rules array match
- Enum
-
- ALL
- ANY
rules
array[]
For group type, the rules array
reference (source_rule)
recursivetags
array[string]
Array of tag strings
string
source
string
Source of rule
member_count
int
Role member count
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
string
- Enum
-
- licenses-manage
- api-clients-manage
- connections-view
- connections-playback
- connections-terminate
- connections-manual
- connections-trail
- hosts-view
- hosts-manage
- privx-host-provisioning
- role-target-resources-view
- role-target-resources-manage
- roles-view
- roles-manage
- sources-view
- sources-manage
- users-view
- users-manage
- logs-view
- logs-manage
- workflows-manage
- workflows-view
- vault-manage
- vault-add
- access-groups-manage
context
object (context)
Contextual limitation
enabled
boolean
Are contextual limitations enabled
block_role
boolean
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.
validity
array[string]
string
Week day on which contextual limitation allows access
- Enum
-
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
start_time
string
Start time of day as HH:MM when contextual limit allows access
end_time
string
End time of day as HH:MM when contextual limit allows access
timezone
string
Time zone of start_time and end_time
ip_masks
array[string]
string
CIDR or IP address where client is connecting from
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
type
string
Is the source rule a single rule or a group
- Enum
-
- RULE
- GROUP
source
string
For single type, the ID of the source provider
search_string
string
For single type, the search string at the source provider.
match
string
For group type, should all or any of the rules in the rules array match
- Enum
-
- ALL
- ANY
rules
array[]
For group type, the rules array
reference (source_rule)
recursivetags
array[string]
Array of tag strings
string
source
string
Source of rule
member_count
int
Role member count
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
OAuth2
Required Scopes:
admin
rolesManage
service
Create a new role definition. ID, author, created & updated fields are automatically populated by the server.
All Scopes
-
admin
· Admin scope - used for built-in PrivX admin account -
apiClient
· API Client scope - used for scripted access -
authorizedKeysManage
· Client with authorizedkeys-manage -
hostsProvisioning
· Deploy script -
roleTargetResourcesManage
· Client with role-target-resources-manage -
roleTargetResourcesView
· Client with role-target-resources-view -
rolesManage
· Client with roles-manage scope -
rolesView
· Client with roles-view scope -
service
· Microservice scope - used for communication between PrivX microservices -
sourcesManage
· Client with sources-manage scope -
sourcesView
· Client with source-view scope -
user
· Normal users -
usersManage
· Client with users-manage scope -
usersView
· Client with users-view scope
- Flow Type:
- authorization_code
- Auth URL:
- https://api.privx.ssh.com/v1/auth/auth
- Token URL:
- https://api.privx.ssh.com/v1/auth/auth
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
Role Successfully created
{
"id": "5bf77342-221c-11ee-be56-0242ac120002"
}
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Bad request
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization missing or invalid
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization OK but scope insufficient
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Resource not found
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Internal server error
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
error_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveid
string
uuid
ID of the created resource
Location
string
Location of the created resource
array[string]
- Content Type
- application/json
string
List of role names to resolve.
Authorization
string
required
OAuth2 token
- Default
- "Bearer trusted-client-credentials-go-here"
OAuth2
Required Scopes:
admin
service
hostsProvisioning
rolesView
Resolve role names to role IDs
All Scopes
-
admin
· Admin scope - used for built-in PrivX admin account -
apiClient
· API Client scope - used for scripted access -
authorizedKeysManage
· Client with authorizedkeys-manage -
hostsProvisioning
· Deploy script -
roleTargetResourcesManage
· Client with role-target-resources-manage -
roleTargetResourcesView
· Client with role-target-resources-view -
rolesManage
· Client with roles-manage scope -
rolesView
· Client with roles-view scope -
service
· Microservice scope - used for communication between PrivX microservices -
sourcesManage
· Client with sources-manage scope -
sourcesView
· Client with source-view scope -
user
· Normal users -
usersManage
· Client with users-manage scope -
usersView
· Client with users-view scope
- Flow Type:
- authorization_code
- Auth URL:
- https://api.privx.ssh.com/v1/auth/auth
- Token URL:
- https://api.privx.ssh.com/v1/auth/auth
Request
[
"string"
]
Response
Roles found, role IDs returned
{
"count": 123,
"items": [
{
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"role_name": "string"
}
]
}
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Bad request
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Resource not found
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Internal server error
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
error_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursivecount
int
The number of found items
items
array[object]
object
id
string
uuid
ID of the role
role_name
string
Name of the role, matches the name in the request
name
array[string]
List of roles names.
string
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
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
OAuth2
Required Scopes:
admin
rolesView
service
Search roles with role search parameters.
All Scopes
-
admin
· Admin scope - used for built-in PrivX admin account -
apiClient
· API Client scope - used for scripted access -
authorizedKeysManage
· Client with authorizedkeys-manage -
hostsProvisioning
· Deploy script -
roleTargetResourcesManage
· Client with role-target-resources-manage -
roleTargetResourcesView
· Client with role-target-resources-view -
rolesManage
· Client with roles-manage scope -
rolesView
· Client with roles-view scope -
service
· Microservice scope - used for communication between PrivX microservices -
sourcesManage
· Client with sources-manage scope -
sourcesView
· Client with source-view scope -
user
· Normal users -
usersManage
· Client with users-manage scope -
usersView
· Client with users-view scope
- Flow Type:
- authorization_code
- Auth URL:
- https://api.privx.ssh.com/v1/auth/auth
- Token URL:
- https://api.privx.ssh.com/v1/auth/auth
Request
{
"name": [
"string"
]
}
Response
Successful response, returns a list of roles
{
"count": 123,
"items": [
{
"id": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
"name": "string",
"type": "string",
"member_count": 123
}
]
}
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Bad request
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization missing or invalid
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization OK but scope insufficient
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Resource not found
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Internal server error
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
error_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursivecount
int
items
array[object]
object
A role definition in roles search response
id
string
uuid
The UUID of the returned object
- Example
- "eef4aefc-d64e-4c2c-aba4-4914c86ce059"
name
string
Name of the role
type
string
role type
member_count
int
Role member count
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]
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
string
- Enum
-
- licenses-manage
- api-clients-manage
- connections-view
- connections-playback
- connections-terminate
- connections-manual
- connections-trail
- hosts-view
- hosts-manage
- privx-host-provisioning
- role-target-resources-view
- role-target-resources-manage
- roles-view
- roles-manage
- sources-view
- sources-manage
- users-view
- users-manage
- logs-view
- logs-manage
- workflows-manage
- workflows-view
- vault-manage
- vault-add
- access-groups-manage
context
object (context)
Contextual limitation
enabled
boolean
Are contextual limitations enabled
block_role
boolean
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.
validity
array[string]
string
Week day on which contextual limitation allows access
- Enum
-
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
start_time
string
Start time of day as HH:MM when contextual limit allows access
end_time
string
End time of day as HH:MM when contextual limit allows access
timezone
string
Time zone of start_time and end_time
ip_masks
array[string]
string
CIDR or IP address where client is connecting from
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
type
string
Is the source rule a single rule or a group
- Enum
-
- RULE
- GROUP
source
string
For single type, the ID of the source provider
search_string
string
For single type, the search string at the source provider.
match
string
For group type, should all or any of the rules in the rules array match
- Enum
-
- ALL
- ANY
rules
array[]
For group type, the rules array
reference (source_rule)
recursivetags
array[string]
Array of tag strings
string
source
string
Source of rule
member_count
int
Role member count
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
OAuth2
Required Scopes:
admin
rolesView
service
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.
All Scopes
-
admin
· Admin scope - used for built-in PrivX admin account -
apiClient
· API Client scope - used for scripted access -
authorizedKeysManage
· Client with authorizedkeys-manage -
hostsProvisioning
· Deploy script -
roleTargetResourcesManage
· Client with role-target-resources-manage -
roleTargetResourcesView
· Client with role-target-resources-view -
rolesManage
· Client with roles-manage scope -
rolesView
· Client with roles-view scope -
service
· Microservice scope - used for communication between PrivX microservices -
sourcesManage
· Client with sources-manage scope -
sourcesView
· Client with source-view scope -
user
· Normal users -
usersManage
· Client with users-manage scope -
usersView
· Client with users-view scope
- Flow Type:
- authorization_code
- Auth URL:
- https://api.privx.ssh.com/v1/auth/auth
- Token URL:
- https://api.privx.ssh.com/v1/auth/auth
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
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"
}
]
}
]
}
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Bad request
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization missing or invalid
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization OK but scope insufficient
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Resource not found
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Internal server error
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
error_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursivecount
int
items
array[object]
object
A user object
id
string
uuid
The UUID of the returned object
- Example
- "eef4aefc-d64e-4c2c-aba4-4914c86ce059"
source_user_id
The originating unique identifer for the user (UUID from local user store, principal from LDAP, ..) - only returned by the Role Store API
created
string
date-time
When the object was created
- Example
- "2017-01-01T15:05:05Z"
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"
author
string
uuid
ID of the user who originally authored the object
- Example
- "eef4aefc-d64e-4c2c-aba4-4914c86ce059"
comment
string
A comment describing the object
- Example
- "A comment"
tags
array[string]
Array of tag strings
string
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 "_"
- Example
- "fi_FI"
roles
array[object]
The array of role IDs the user has. Boolean "explicit" denotes whether the role is granted explicitly or implicitly via a mapping.
object
A simple role handle for getting & updating user roles
id
string
uuid
name
string
comment
string
A comment describing the object
- Example
- "A comment"
principal_public_key_strings
array[string]
Principal public keys, returned only from /users/resolve
string
permit_agent
boolean
Permit agent, returned only from /users/resolve
access_group_id
string
uuid
Scopes host and connection permissions to an access group
permissions
array[string]
Array of permissions
string
- Enum
-
- licenses-manage
- api-clients-manage
- connections-view
- connections-playback
- connections-terminate
- connections-manual
- connections-trail
- hosts-view
- hosts-manage
- privx-host-provisioning
- role-target-resources-view
- role-target-resources-manage
- roles-view
- roles-manage
- sources-view
- sources-manage
- users-view
- users-manage
- logs-view
- logs-manage
- workflows-manage
- workflows-view
- vault-manage
- vault-add
- access-groups-manage
context
object (context)
Contextual limitation
enabled
boolean
Are contextual limitations enabled
block_role
boolean
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.
validity
array[string]
string
Week day on which contextual limitation allows access
- Enum
-
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
start_time
string
Start time of day as HH:MM when contextual limit allows access
end_time
string
End time of day as HH:MM when contextual limit allows access
timezone
string
Time zone of start_time and end_time
ip_masks
array[string]
string
CIDR or IP address where client is connecting from
explicit
boolean
Is the role explicitly granted to the user
- Default
- false
implicit
boolean
Has the user implicitly gained the role or not.
- Default
- false
system
boolean
- Default
- 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.
- Enum
-
- PERMANENT
- TIME_RESTRICTED
- FLOATING
grant_validity_periods
array[object]
Array of validity periods for this role. This array replaces grant_start and grant_end attributes in role object.
object
An object describing the start and end validity times for this role.
grant_start
string
date-time
Date & time after which the role is granted to the user in ISO8601
- Example
- "2017-01-01T15:05:05Z"
grant_end
string
date-time
Date & time after which the role is removed from the user in ISO8601
- Example
- "2017-01-02T15:05:05Z"
floating_length
int
Duration for which the grant should last after initial connection, specified in hours
- Example
- 24
attributes
array[object]
Custom user attributes array.
object
Custom user attributes
key
string
required
- Example
- "aws_account"
value
string
required
- Example
- "admin-bob"
permissions
array[string]
Array of permissions
string
- Enum
-
- licenses-manage
- api-clients-manage
- connections-view
- connections-playback
- connections-terminate
- connections-manual
- hosts-view
- hosts-manage
- host-provisioning
- role-target-resources-view
- role-target-resources-manage
- roles-view
- roles-manage
- sources-view
- sources-manage
- users-view
- users-manage
- logs-view
- logs-manage
- workflows-manage
- workflows-view
- network-targets-view
- network-targets-manage
source
string
Source ID
mfa
object (mfa)
status
string
- Enum
-
- ENABLED
- DISABLED
- UNINITIALIZED
seed
object (seed)
seed_string
string
The MFA seed in textual format
seed_qr_code
string
The MFA-seed QR code in base64 encoded format (PNG file)
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[object]
object
id
string
uuid
Unique identifier for authorized key
- Example
- "2765b005-4ce1-4b2b-a9ca-ee6c4d6f2792"
username
string
Username of the authorized key owner
- Example
- "joe@privx.com"
user_id
string
uuid
User id of the authorized key owner
- Example
- "f2f448d8-0397-4894-982f-9a58a43921db"
source
string
uuid
User source ID
name
string
required
Name for authorized key
- Example
- "work"
comment
string
Comment for authorized key
- Example
- "Joe's work laptop key"
public_key
string
Public key data in ssh authorized key format
- Example
- "AAAAB3NzaC1yc2EAAAADAQABAAABAQDqoMogqErOw7lL3GD6Ez7Hv1FZBk0Iyk2pBFUhqb9sjY9IEw8P9OWFwLMhWQ4LNvekPAnmr03pMHSSP7Pw98+Izy0HxcHZGKcrDOIjnHF5Fog3w4rBYa6OxdcJRxctifx5szqmM4JkUNS1RJY5E4ns4xCgFV46Satph02M+eP9PXGh+ZecSNtdLoOovVuolEUdb8dINgto8zsjEuAQ+76qOEgAIuSsYlzGGZPyPnATtkUi/rK9fcAfbhSqSXNxFqf7wejEKwA1kFt8hSW2bUWJH268fqnejFwHjBTzjBw89dji6141ajAP8/Q2gZug0bb1U70PE4afE3fFh2VCfhwT"
not_before
string
date-time
Start of key validity period
- Example
- "2020-07-31T17:32:28Z"
not_after
string
date-time
End of key validity period
- Example
- "2022-07-31T17:32:28Z"
expires_in
int
Time in seconds to key expiry. Value is not set if key is not yet valid.
source_address
array[string]
string
IP address or CIDR
- Example
- "192.168.100.0/24"
fingerprints
array[string]
string
Public key fingerprint
- Example
- "SHA256:bdeYZ2qiEwCOCuf0oTvya/aH4Vo+nJLIauDKm/D8btM"
webauthn_credentials
array[object]
object
Webauthn credential
id
string
uuid
required
Credential UUID
credential_id
string
Webauthn credential ID
name
string
Credential name
comment
string
Optional comment
last_used
string
date-time
Timestamp of last login event using this credential
- Example
- "2017-01-01T15:05:05Z"
created
string
date-time
Creation timestamp
- Example
- "2017-01-01T15:05:05Z"
author
string
uuid
ID of the user who originally authored the object
updated
string
date-time
Update timestamp
- Example
- "2017-01-01T15:05:05Z"
updated_by
string
uuid
ID of the user who updated the object
- Example
- "eef4aefc-d64e-4c2c-aba4-4914c86ce059"
role_id
string
required
Role ID
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
OAuth2
Required Scopes:
admin
rolesView
service
Get role object by ID.
All Scopes
-
admin
· Admin scope - used for built-in PrivX admin account -
apiClient
· API Client scope - used for scripted access -
authorizedKeysManage
· Client with authorizedkeys-manage -
hostsProvisioning
· Deploy script -
roleTargetResourcesManage
· Client with role-target-resources-manage -
roleTargetResourcesView
· Client with role-target-resources-view -
rolesManage
· Client with roles-manage scope -
rolesView
· Client with roles-view scope -
service
· Microservice scope - used for communication between PrivX microservices -
sourcesManage
· Client with sources-manage scope -
sourcesView
· Client with source-view scope -
user
· Normal users -
usersManage
· Client with users-manage scope -
usersView
· Client with users-view scope
- Flow Type:
- authorization_code
- Auth URL:
- https://api.privx.ssh.com/v1/auth/auth
- Token URL:
- https://api.privx.ssh.com/v1/auth/auth
Response
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
}
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Bad request
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization missing or invalid
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization OK but scope insufficient
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Resource not found
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Internal server error
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
error_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveid
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]
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
string
- Enum
-
- licenses-manage
- api-clients-manage
- connections-view
- connections-playback
- connections-terminate
- connections-manual
- connections-trail
- hosts-view
- hosts-manage
- privx-host-provisioning
- role-target-resources-view
- role-target-resources-manage
- roles-view
- roles-manage
- sources-view
- sources-manage
- users-view
- users-manage
- logs-view
- logs-manage
- workflows-manage
- workflows-view
- vault-manage
- vault-add
- access-groups-manage
context
object (context)
Contextual limitation
enabled
boolean
Are contextual limitations enabled
block_role
boolean
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.
validity
array[string]
string
Week day on which contextual limitation allows access
- Enum
-
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
start_time
string
Start time of day as HH:MM when contextual limit allows access
end_time
string
End time of day as HH:MM when contextual limit allows access
timezone
string
Time zone of start_time and end_time
ip_masks
array[string]
string
CIDR or IP address where client is connecting from
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
type
string
Is the source rule a single rule or a group
- Enum
-
- RULE
- GROUP
source
string
For single type, the ID of the source provider
search_string
string
For single type, the search string at the source provider.
match
string
For group type, should all or any of the rules in the rules array match
- Enum
-
- ALL
- ANY
rules
array[]
For group type, the rules array
reference (source_rule)
recursivetags
array[string]
Array of tag strings
string
source
string
Source of rule
member_count
int
Role member count
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
string
- Enum
-
- licenses-manage
- api-clients-manage
- connections-view
- connections-playback
- connections-terminate
- connections-manual
- connections-trail
- hosts-view
- hosts-manage
- privx-host-provisioning
- role-target-resources-view
- role-target-resources-manage
- roles-view
- roles-manage
- sources-view
- sources-manage
- users-view
- users-manage
- logs-view
- logs-manage
- workflows-manage
- workflows-view
- vault-manage
- vault-add
- access-groups-manage
context
object (context)
Contextual limitation
enabled
boolean
Are contextual limitations enabled
block_role
boolean
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.
validity
array[string]
string
Week day on which contextual limitation allows access
- Enum
-
- MON
- TUE
- WED
- THU
- FRI
- SAT
- SUN
start_time
string
Start time of day as HH:MM when contextual limit allows access
end_time
string
End time of day as HH:MM when contextual limit allows access
timezone
string
Time zone of start_time and end_time
ip_masks
array[string]
string
CIDR or IP address where client is connecting from
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
type
string
Is the source rule a single rule or a group
- Enum
-
- RULE
- GROUP
source
string
For single type, the ID of the source provider
search_string
string
For single type, the search string at the source provider.
match
string
For group type, should all or any of the rules in the rules array match
- Enum
-
- ALL
- ANY
rules
array[]
For group type, the rules array
reference (source_rule)
recursivetags
array[string]
Array of tag strings
string
source
string
Source of rule
member_count
int
Role member count
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
role_id
string
required
Role ID
OAuth2
Required Scopes:
admin
rolesManage
service
Update a role.
All Scopes
-
admin
· Admin scope - used for built-in PrivX admin account -
apiClient
· API Client scope - used for scripted access -
authorizedKeysManage
· Client with authorizedkeys-manage -
hostsProvisioning
· Deploy script -
roleTargetResourcesManage
· Client with role-target-resources-manage -
roleTargetResourcesView
· Client with role-target-resources-view -
rolesManage
· Client with roles-manage scope -
rolesView
· Client with roles-view scope -
service
· Microservice scope - used for communication between PrivX microservices -
sourcesManage
· Client with sources-manage scope -
sourcesView
· Client with source-view scope -
user
· Normal users -
usersManage
· Client with users-manage scope -
usersView
· Client with users-view scope
- Flow Type:
- authorization_code
- Auth URL:
- https://api.privx.ssh.com/v1/auth/auth
- Token URL:
- https://api.privx.ssh.com/v1/auth/auth
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
Role successfully updated
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
Empty response
No schema
Bad request
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization missing or invalid
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Unauthorized request, OAuth2 authorization OK but scope insufficient
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Resource not found
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
Internal server error
{
"error_code": "GENERAL_ERROR",
"error_message": "string",
"property": "string",
"details": [
null
]
}
error_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail
reference (error)
recursiveerror_code
string
required
Standard error code denoting the error type
- Enum
-
- GENERAL_ERROR
- BAD_REQUEST
- PERMISSION_DENIED
- INVALID_REQUEST_DATA
- REQUIRED_VALUE_MISSING
- VALUE_OUT_OF_BOUNDS
- VALUE_INCORRECT_TYPE
- VALUE_INCORRECT_FORMAT
- VALUE_DUPLICATE
- CONFIGURATION_ERROR
- OUT_OF_RESOURCES
- MAX_LOAD
- TOO_MANY_CONNECTIONS
- DATABASE_ERROR
- CACHE_ERROR
- INTRA_SERVICE_COMMUNICATION_ERROR
error_message
string
Textual, human readable error message
property
string
The property name causing the error
details
array[]
An array of errors describing the error in more detail