hosts
Download Specignore_disabled_sources
boolean
Ignores the disabled hosts - when enabled, host search searches for disabled hosts as well
keywords
string
Comma or space-separated strings to search across all host attributes. The leading and trailing wildcards for the keywords are implicit.
distinguished_name
array[string]
A comma separated list of strings to search for
string
external_id
string
The external id of the host
instance_id
string
The instance id from the cloud service
source_id
string
The source of the host
common_name
array[string]
An array of strings to search for
string
organization
array[string]
An array of strings to search for
string
organizational_unit
array[string]
An array of strings to search for
string
address
array[string]
An array of strings to search for
string
access_group_ids
array[string]
An array of access group IDs to search for
string
uuid
service
array[string]
An array of service types to search for (SSH, RDP, WEB, VNC, DB)
string
port
array[int]
An array of integers to search for
int
zone
array[string]
An array of strings to search for
string
host_type
array[string]
An array of strings to search for
string
host_classification
array[string]
An array of strings to search for
string
role
array[string]
An array of strings to search for (role id's)
string
scope
array[string]
An array of strings to search for
string
tags
array[string]
An array of host tags to search for
string
cloud_providers
array[string]
An array of cloud provider names to search (AWS,GOOGLECLOUD,AZURE,OPENSTACK)
string
cloud_provider_regions
array[string]
An array of cloud provider regions to search for. Valid values depend on cloud provider.
string
deployable
boolean
A host deployable flag status to search for.
statuses
array[string]
An array of host status strings to search for.
string
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
offset
int
Offset from which to start fetching objects
- Default
- 0
limit
int
Maximum number of objects to return
- Default
- 50
sortkey
string
Sort by specific object property
- Default
- "id"
sortdir
string
Sort direction, asc or desc
- Default
- "ASC"
- Enum
-
- ASC
- DESC
filter
string
Filter hosts - possible values: accessible (filter hosts based on whether the current user has access to them)
oauth
Required Scopes:
admin
service
hostsView
user
Search for hosts
All Scopes
-
admin
· Admin scope - used for built-in PrivX admin account -
hostsManage
· Clients with hosts-manage scope -
hostsProvisioning
· Deploy script users -
hostsView
· Clients with hosts-view scope -
service
· Microservice scope - used for communication between PrivX microservices -
user
· Normal users
- Flow Type:
- authorization_code
- Auth URL:
- https://api.x.com/v1/auth/auth
- Token URL:
- https://api.x.com/v1/auth/auth
Request
{
"ignore_disabled_sources": true,
"keywords": "string",
"distinguished_name": [
"string"
],
"external_id": "string",
"instance_id": "string",
"source_id": "string",
"common_name": [
"string"
],
"organization": [
"string"
],
"organizational_unit": [
"string"
],
"address": [
"string"
],
"access_group_ids": [
"5bf77342-221c-11ee-be56-0242ac120002"
],
"service": [
"string"
],
"port": [
123
],
"zone": [
"string"
],
"host_type": [
"string"
],
"host_classification": [
"string"
],
"role": [
"string"
],
"scope": [
"string"
],
"tags": [
"string"
],
"cloud_providers": [
"string"
],
"cloud_provider_regions": [
"string"
],
"deployable": true,
"statuses": [
"string"
]
}
Response
Search successful, return matching hosts
{
"count": 123,
"items": [
{
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
"deployable": true,
"tofu": true,
"stand_alone_host": true,
"external_id": "string",
"instance_id": "string",
"audit_enabled": true,
"session_recording_options": {
"disable_clipboard_recording": true,
"disable_file_transfer_recording": true
},
"ssh_host_public_keys": [
{
"key": "string",
"fingerprint": "string"
}
],
"host_certificate_raw": "string",
"host_certificate": {
"subject": "string",
"issuer": "string",
"serial": "string",
"not_before": "string",
"not_after": "string",
"dns_names": [
"string"
],
"email_addresses": [
"string"
],
"ip_addresses": [
"string"
],
"fingerprint_sha1": "string",
"fingerprint_sha256": "string"
},
"contact_address": "string",
"services": [
{
"service": "SSH",
"address": "string",
"port": 123,
"use_for_password_rotation": true,
"ssh_tunnel_port": 123,
"source": "string",
"login_page_url": "string",
"username_field_name": "string",
"password_field_name": "string",
"login_request_url": "string",
"login_request_password_property": "string",
"auth_type": "string",
"status": "OK",
"status_updated": "string",
"allowed_domains": [
"string"
],
"service_version": "string",
"use_legacy_cipher_suites": true,
"tls_min_version": "string",
"tls_max_version": "string",
"browser": "string",
"db": {
"protocol": "postgres",
"tls_certificate_validation": "ENABLED",
"tls_certificate_trust_anchors": "string",
"audit_skip_bytes": 123
},
"created": "2017-01-01T15:05:05Z",
"updated": "2017-01-01T15:05:05Z",
"certificate_template": "string"
}
],
"principals": [
{
"principal": "string",
"rotate": true,
"use_user_account": true,
"passphrase": "string",
"username_attribute": "string",
"source": "string",
"roles": [
{
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string",
"deleted": true
}
],
"applications": [
{
"name": "string",
"application": "string",
"arguments": "string",
"working_directory": "string"
}
],
"service_options": {
"ssh": {
"shell": true,
"file_transfer": true,
"exec": true,
"tunnels": true,
"x11": true,
"other": true
},
"rdp": {
"file_transfer": true,
"audio": true,
"clipboard": true
},
"web": {
"file_transfer": true,
"audio": true,
"clipboard": true
},
"vnc": {
"file_transfer": true,
"clipboard": true
},
"db": {
"max_bytes_download": 123,
"max_bytes_upload": 123
}
},
"command_restrictions": {
"enabled": true,
"default_whitelist": {
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string",
"deleted": true
},
"rshell_variant": "bash",
"banner": "string",
"allow_no_match": true,
"audit_match": true,
"audit_no_match": true,
"whitelists": [
{
"whitelist": {
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string",
"deleted": true
},
"roles": [
{
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string"
}
]
}
]
}
}
],
"password_rotation_enabled": true,
"password_rotation": {
"access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
"use_main_account": true,
"operating_system": "LINUX",
"winrm_address": "string",
"winrm_port": 123,
"protocol": "SSH",
"certificate_validation_options": "DISABLED",
"winrm_host_certificate_trust_anchors": "string",
"password_policy_id": "5bf77342-221c-11ee-be56-0242ac120002",
"script_template_id": "5bf77342-221c-11ee-be56-0242ac120002",
"rotation_status": [
{
"principal": "string",
"last_rotated": "2017-01-01T15:05:05Z",
"last_error": "2017-01-01T15:05:05Z",
"last_error_details": "string"
}
],
"created": "2017-01-01T15:05:05Z",
"updated": "2017-01-01T15:05:05Z",
"created_by": "string",
"updated_by": "string"
},
"source_id": "string",
"cloud_provider": "string",
"cloud_provider_region": "string",
"status": [
{
"k": "string",
"v": "string"
}
],
"created": "2017-01-01T15:05:05Z",
"updated": "2017-01-01T15:05:05Z",
"updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
"distinguished_name": "string",
"common_name": "string",
"organization": "string",
"organizational_unit": "string",
"zone": "string",
"scope": [
"string"
],
"host_type": "string",
"host_classification": "string",
"comment": "string",
"addresses": [
"string"
],
"tags": [
"string"
],
"disabled": "BY_ADMIN"
}
]
}
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 standard equipment definition
id
string
uuid
access_group_id
string
uuid
Defines host's access group
deployable
boolean
Whether the host is writable through /deploy end point with deployment credentials
tofu
boolean
Whether the host key should be accepted and stored on first connection
stand_alone_host
boolean
Indicates it is a standalone host - bound to local host directory
external_id
string
The equipment ID from the originating equipment store
instance_id
string
The instance ID from the originating cloud service (searchable by keyword)
audit_enabled
boolean
Wheter the host is set to be audited.
session_recording_options
object (session_recording_options)
Flags to disable trail auditing for certain features when auditing is enabled
disable_clipboard_recording
boolean
Disable clipboard trail auditing when auditing is enabled
disable_file_transfer_recording
boolean
Disable file transfer trail auditing when auditing is enabled
ssh_host_public_keys
array[object]
object
key
string
Host public key, used to verify the identity of the accessed host
fingerprint
string
The host-key fingerprint
host_certificate_raw
string
Host certificate, used to verify that the target host is the correct one.
host_certificate
object (host_certificate)
subject
string
Certificate subject name
issuer
string
Certificate issuer name
serial
string
Certificate serial number
not_before
string
Certificate not before timestamp
not_after
string
Certificate not after timestamp
dns_names
array[string]
string
Certificate DNS subject alternative name
email_addresses
array[string]
string
Certificate email address subject alternative name
ip_addresses
array[string]
string
Certificate IP address subject alternative name
fingerprint_sha1
string
Certificate SHA1 fingerprint
fingerprint_sha256
string
Certificate SHA256 fingerprint
contact_address
string
The host public address scanning script instructs the host store to use in service address-field.
services
array[object]
object
service
string
Allowed protocol - SSH, RDP, VNC, WEB, DB (searchable)
- Enum
-
- SSH
- RDP
- VNC
- WEB
- DB
address
string
Service address, IPv4, IPv6 or FQDN
port
int
Service port
use_for_password_rotation
boolean
if service SSH, informs whether this service is used to rotate password
- Default
- false
ssh_tunnel_port
int
ssh tunnel port
source
string
Identifies the source of the services object "UI", "SCIM" or "SCAN". Deploy is also treated as "UI".
login_page_url
string
username_field_name
string
password_field_name
string
login_request_url
string
login_request_password_property
string
auth_type
string
status
string
- Example
- "OK"
status_updated
string
allowed_domains
array[string]
List of allowed domains
string
service_version
string
use_legacy_cipher_suites
boolean
tls_min_version
string
tls_max_version
string
browser
string
db
object (db)
protocol
string
Database protocol
- Enum
-
- postgres
- mysql
- passthrough
- tls
tls_certificate_validation
string
- Enum
-
- ENABLED
- DISABLED
tls_certificate_trust_anchors
string
Database server TLS certificate trust anchors in PEM
audit_skip_bytes
int
Session recording of the protocol stream will start only when this amount of bytes have been transferred from client to server. Set to zero to start session recording from start of protocol stream.
created
string
date-time
When the object was created
- Example
- "2017-01-01T15:05:05Z"
updated
string
date-time
When the object was updated
- Example
- "2017-01-01T15:05:05Z"
certificate_template
string
Name of the certificate template used for certificate authentication for this host
principals
array[object]
What principals (target server user names/ accounts) the host has
object
principal
string
The account name
rotate
boolean
Secret is rotating pasword
use_user_account
boolean
Use user account as host principal name
passphrase
string
The account static passphrase or the initial rotating password value
username_attribute
string
Custom username attribute
source
string
Identifies the source of the principals object "UI" or "SCAN". Deploy is also treated as "UI".
roles
array[object]
An array of roles entitled to access this principal on the host
object
id
string
uuid
Role UUID
name
string
Role display_name
deleted
boolean
Role is deleted
applications
array[object]
An array of application the principal may launch on the target host
object
application the principal may launch on the target host
name
string
application
string
arguments
string
working_directory
string
service_options
object (service_options)
Object for service options
ssh
object (ssh)
SSH service options
shell
boolean
Shell channel
file_transfer
boolean
File transfer channel
exec
boolean
exec channel
tunnels
boolean
tunnels
x11
boolean
x11
other
boolean
other options
rdp
object (rdp)
RDP service options
file_transfer
boolean
file transfer
audio
boolean
audio
clipboard
boolean
clipboard
web
object (web)
WEB service options
file_transfer
boolean
file transfer
audio
boolean
audio
clipboard
boolean
clipboard
vnc
object (vnc)
VNC service options
file_transfer
boolean
file transfer
clipboard
boolean
clipboard
db
object (db)
DB service options
max_bytes_download
int
Maximum number of bytes allowed in download direction per connection. Set to zero to disable byte count limiting.
max_bytes_upload
int
Maximum number of bytes allowed in upload direction per connection. Set to zero to disable byte count limiting.
command_restrictions
object (command_restrictions)
SSH shell/exec command restrictions for the principal
enabled
boolean
Are command restrictions enabled
default_whitelist
object (default_whitelist)
Default whitelist handle, required if command restrictions are enabled
id
string
uuid
required
Whitelist ID
name
string
Whitelist name
deleted
boolean
Has whitelist been deleted, ignored in requests
rshell_variant
string
Restricted shell variant, required if command restrictions are enabled
- Enum
-
- bash
- posix
banner
string
Optional banner displayed in SSH terminal
allow_no_match
boolean
If true then commands that do not match any whitelist pattern are allowed to execute
audit_match
boolean
If true then an audit event is generated for every allowed command
audit_no_match
boolean
If true then an audit event is generated for every disallowed command
whitelists
array[object]
object
additional whitelist grant
whitelist
object (whitelist)
id
string
uuid
required
Whitelist ID
name
string
Whitelist name
deleted
boolean
Has whitelist been deleted, ignored in requests
roles
array[object]
List of roles granting access to the whitelist
object
id
string
uuid
required
Role ID
name
string
Role name
password_rotation_enabled
boolean
set, if there are accounts, in which passwords need to be rotated
password_rotation
object (password_rotation)
password rotation settings for host
access_group_id
string
uuid
Specify ID of access group, default access group will be used if ID is not specified. Access group will be checked for WinRM trust anchors if certificate validation option is set to enabled.
use_main_account
boolean
required
rotate passwords of all accounts in host through one account
operating_system
string
required
Bash for Linux, Powershell for windows for shell access
- Enum
-
- LINUX
- WINDOWS
winrm_address
string
IPv4 address or FQDN to use for winrm connections
winrm_port
int
port to use for password rotation with winrm, zero for winrm default
protocol
string
required
- Enum
-
- SSH
- WINRM
certificate_validation_options
string
required
Disable or enable password rotation certificate validation
- Enum
-
- DISABLED
- ENABLED
winrm_host_certificate_trust_anchors
string
WinRM host certificate trust anchors in PEM format
password_policy_id
string
uuid
required
password policy to be applied
script_template_id
string
uuid
required
script template to be run in host
rotation_status
array[object]
Filled by backend. Rotation status per account to be shown in UI
object
principal
string
last_rotated
string
date-time
When last successful rotation. Added by backend
- Example
- "2017-01-01T15:05:05Z"
last_error
string
date-time
Last rotation error. Cleared when rotation successful, updated by backend
- Example
- "2017-01-01T15:05:05Z"
last_error_details
string
information of rotation error, updated by backend
created
string
date-time
When the object was created. Added by backend
- Example
- "2017-01-01T15:05:05Z"
updated
string
date-time
When the object was updated. Added by backend
- Example
- "2017-01-01T15:05:05Z"
created_by
string
added by backend
updated_by
string
added by backend
source_id
string
A unique import-source identifier for the host entry, for example a hash for AWS account ID. (searchable by keyword)
cloud_provider
string
The cloud provider this host resides in
cloud_provider_region
string
The cloud provider region the host resides in
status
array[object]
object
k
string
v
string
created
string
date-time
When the object was created
- Example
- "2017-01-01T15:05:05Z"
updated
string
date-time
When the object was updated
- Example
- "2017-01-01T15:05:05Z"
updated_by
string
uuid
Id of the user who updated the object
- Example
- "eef4aefc-d64e-4c2c-aba4-4914c86ce059"
distinguished_name
string
LDAPv3 Disinguished name (searchable by keyword)
common_name
string
X.500 Common name (searchable by keyword)
organization
string
X.500 Organization (searchable by keyword)
organizational_unit
string
X.500 Organizational unit (searchable by keyword)
zone
string
Equipment zone (development, production, user acceptance testing, ..) (searchable by keyword)
scope
array[string]
Under what compliance scopes the listed equipment falls under (searchable by keyword)
string
Compliancy requirement (PCI, HIPAA, ..)
host_type
string
Equipment type (virtual, physical) (searchable by keyword)
host_classification
string
Classification (Windows desktop, Windows server, AIX, Linux RH, ..) (searchable by keyword)
comment
string
A comment describing the host
addresses
array[string]
string
Fully qualified domain names, and/or IPv4 or IPv6 addresses of the host (searchable by keyword)
tags
array[string]
string
disabled
string
- Enum
-
- BY_ADMIN
- BY_LICENSE
offset
int
Offset from which to start fetching objects
- Default
- 0
limit
int
Maximum number of objects to return
- Default
- 50
sortkey
string
Sort by specific object property
- Default
- "id"
sortdir
string
Sort direction, asc or desc
- Default
- "ASC"
- Enum
-
- ASC
- DESC
filter
string
Filter hosts - possible values: accessible (filter hosts based on whether the current user has access to them) and configured (list only hosts with services)
- Enum
-
- accessible
- configured
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
oauth
Required Scopes:
admin
user
hostsView
service
Get hosts
All Scopes
-
admin
· Admin scope - used for built-in PrivX admin account -
hostsManage
· Clients with hosts-manage scope -
hostsProvisioning
· Deploy script users -
hostsView
· Clients with hosts-view scope -
service
· Microservice scope - used for communication between PrivX microservices -
user
· Normal users
- Flow Type:
- authorization_code
- Auth URL:
- https://api.x.com/v1/auth/auth
- Token URL:
- https://api.x.com/v1/auth/auth
Response
Successful request, respond with a list of hosts
{
"count": 123,
"items": [
{
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
"deployable": true,
"tofu": true,
"stand_alone_host": true,
"external_id": "string",
"instance_id": "string",
"audit_enabled": true,
"session_recording_options": {
"disable_clipboard_recording": true,
"disable_file_transfer_recording": true
},
"ssh_host_public_keys": [
{
"key": "string",
"fingerprint": "string"
}
],
"host_certificate_raw": "string",
"host_certificate": {
"subject": "string",
"issuer": "string",
"serial": "string",
"not_before": "string",
"not_after": "string",
"dns_names": [
"string"
],
"email_addresses": [
"string"
],
"ip_addresses": [
"string"
],
"fingerprint_sha1": "string",
"fingerprint_sha256": "string"
},
"contact_address": "string",
"services": [
{
"service": "SSH",
"address": "string",
"port": 123,
"use_for_password_rotation": true,
"ssh_tunnel_port": 123,
"source": "string",
"login_page_url": "string",
"username_field_name": "string",
"password_field_name": "string",
"login_request_url": "string",
"login_request_password_property": "string",
"auth_type": "string",
"status": "OK",
"status_updated": "string",
"allowed_domains": [
"string"
],
"service_version": "string",
"use_legacy_cipher_suites": true,
"tls_min_version": "string",
"tls_max_version": "string",
"browser": "string",
"db": {
"protocol": "postgres",
"tls_certificate_validation": "ENABLED",
"tls_certificate_trust_anchors": "string",
"audit_skip_bytes": 123
},
"created": "2017-01-01T15:05:05Z",
"updated": "2017-01-01T15:05:05Z",
"certificate_template": "string"
}
],
"principals": [
{
"principal": "string",
"rotate": true,
"use_user_account": true,
"passphrase": "string",
"username_attribute": "string",
"source": "string",
"roles": [
{
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string",
"deleted": true
}
],
"applications": [
{
"name": "string",
"application": "string",
"arguments": "string",
"working_directory": "string"
}
],
"service_options": {
"ssh": {
"shell": true,
"file_transfer": true,
"exec": true,
"tunnels": true,
"x11": true,
"other": true
},
"rdp": {
"file_transfer": true,
"audio": true,
"clipboard": true
},
"web": {
"file_transfer": true,
"audio": true,
"clipboard": true
},
"vnc": {
"file_transfer": true,
"clipboard": true
},
"db": {
"max_bytes_download": 123,
"max_bytes_upload": 123
}
},
"command_restrictions": {
"enabled": true,
"default_whitelist": {
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string",
"deleted": true
},
"rshell_variant": "bash",
"banner": "string",
"allow_no_match": true,
"audit_match": true,
"audit_no_match": true,
"whitelists": [
{
"whitelist": {
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string",
"deleted": true
},
"roles": [
{
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string"
}
]
}
]
}
}
],
"password_rotation_enabled": true,
"password_rotation": {
"access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
"use_main_account": true,
"operating_system": "LINUX",
"winrm_address": "string",
"winrm_port": 123,
"protocol": "SSH",
"certificate_validation_options": "DISABLED",
"winrm_host_certificate_trust_anchors": "string",
"password_policy_id": "5bf77342-221c-11ee-be56-0242ac120002",
"script_template_id": "5bf77342-221c-11ee-be56-0242ac120002",
"rotation_status": [
{
"principal": "string",
"last_rotated": "2017-01-01T15:05:05Z",
"last_error": "2017-01-01T15:05:05Z",
"last_error_details": "string"
}
],
"created": "2017-01-01T15:05:05Z",
"updated": "2017-01-01T15:05:05Z",
"created_by": "string",
"updated_by": "string"
},
"source_id": "string",
"cloud_provider": "string",
"cloud_provider_region": "string",
"status": [
{
"k": "string",
"v": "string"
}
],
"created": "2017-01-01T15:05:05Z",
"updated": "2017-01-01T15:05:05Z",
"updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
"distinguished_name": "string",
"common_name": "string",
"organization": "string",
"organizational_unit": "string",
"zone": "string",
"scope": [
"string"
],
"host_type": "string",
"host_classification": "string",
"comment": "string",
"addresses": [
"string"
],
"tags": [
"string"
],
"disabled": "BY_ADMIN"
}
]
}
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 standard equipment definition
id
string
uuid
access_group_id
string
uuid
Defines host's access group
deployable
boolean
Whether the host is writable through /deploy end point with deployment credentials
tofu
boolean
Whether the host key should be accepted and stored on first connection
stand_alone_host
boolean
Indicates it is a standalone host - bound to local host directory
external_id
string
The equipment ID from the originating equipment store
instance_id
string
The instance ID from the originating cloud service (searchable by keyword)
audit_enabled
boolean
Wheter the host is set to be audited.
session_recording_options
object (session_recording_options)
Flags to disable trail auditing for certain features when auditing is enabled
disable_clipboard_recording
boolean
Disable clipboard trail auditing when auditing is enabled
disable_file_transfer_recording
boolean
Disable file transfer trail auditing when auditing is enabled
ssh_host_public_keys
array[object]
object
key
string
Host public key, used to verify the identity of the accessed host
fingerprint
string
The host-key fingerprint
host_certificate_raw
string
Host certificate, used to verify that the target host is the correct one.
host_certificate
object (host_certificate)
subject
string
Certificate subject name
issuer
string
Certificate issuer name
serial
string
Certificate serial number
not_before
string
Certificate not before timestamp
not_after
string
Certificate not after timestamp
dns_names
array[string]
string
Certificate DNS subject alternative name
email_addresses
array[string]
string
Certificate email address subject alternative name
ip_addresses
array[string]
string
Certificate IP address subject alternative name
fingerprint_sha1
string
Certificate SHA1 fingerprint
fingerprint_sha256
string
Certificate SHA256 fingerprint
contact_address
string
The host public address scanning script instructs the host store to use in service address-field.
services
array[object]
object
service
string
Allowed protocol - SSH, RDP, VNC, WEB, DB (searchable)
- Enum
-
- SSH
- RDP
- VNC
- WEB
- DB
address
string
Service address, IPv4, IPv6 or FQDN
port
int
Service port
use_for_password_rotation
boolean
if service SSH, informs whether this service is used to rotate password
- Default
- false
ssh_tunnel_port
int
ssh tunnel port
source
string
Identifies the source of the services object "UI", "SCIM" or "SCAN". Deploy is also treated as "UI".
login_page_url
string
username_field_name
string
password_field_name
string
login_request_url
string
login_request_password_property
string
auth_type
string
status
string
- Example
- "OK"
status_updated
string
allowed_domains
array[string]
List of allowed domains
string
service_version
string
use_legacy_cipher_suites
boolean
tls_min_version
string
tls_max_version
string
browser
string
db
object (db)
protocol
string
Database protocol
- Enum
-
- postgres
- mysql
- passthrough
- tls
tls_certificate_validation
string
- Enum
-
- ENABLED
- DISABLED
tls_certificate_trust_anchors
string
Database server TLS certificate trust anchors in PEM
audit_skip_bytes
int
Session recording of the protocol stream will start only when this amount of bytes have been transferred from client to server. Set to zero to start session recording from start of protocol stream.
created
string
date-time
When the object was created
- Example
- "2017-01-01T15:05:05Z"
updated
string
date-time
When the object was updated
- Example
- "2017-01-01T15:05:05Z"
certificate_template
string
Name of the certificate template used for certificate authentication for this host
principals
array[object]
What principals (target server user names/ accounts) the host has
object
principal
string
The account name
rotate
boolean
Secret is rotating pasword
use_user_account
boolean
Use user account as host principal name
passphrase
string
The account static passphrase or the initial rotating password value
username_attribute
string
Custom username attribute
source
string
Identifies the source of the principals object "UI" or "SCAN". Deploy is also treated as "UI".
roles
array[object]
An array of roles entitled to access this principal on the host
object
id
string
uuid
Role UUID
name
string
Role display_name
deleted
boolean
Role is deleted
applications
array[object]
An array of application the principal may launch on the target host
object
application the principal may launch on the target host
name
string
application
string
arguments
string
working_directory
string
service_options
object (service_options)
Object for service options
ssh
object (ssh)
SSH service options
shell
boolean
Shell channel
file_transfer
boolean
File transfer channel
exec
boolean
exec channel
tunnels
boolean
tunnels
x11
boolean
x11
other
boolean
other options
rdp
object (rdp)
RDP service options
file_transfer
boolean
file transfer
audio
boolean
audio
clipboard
boolean
clipboard
web
object (web)
WEB service options
file_transfer
boolean
file transfer
audio
boolean
audio
clipboard
boolean
clipboard
vnc
object (vnc)
VNC service options
file_transfer
boolean
file transfer
clipboard
boolean
clipboard
db
object (db)
DB service options
max_bytes_download
int
Maximum number of bytes allowed in download direction per connection. Set to zero to disable byte count limiting.
max_bytes_upload
int
Maximum number of bytes allowed in upload direction per connection. Set to zero to disable byte count limiting.
command_restrictions
object (command_restrictions)
SSH shell/exec command restrictions for the principal
enabled
boolean
Are command restrictions enabled
default_whitelist
object (default_whitelist)
Default whitelist handle, required if command restrictions are enabled
id
string
uuid
required
Whitelist ID
name
string
Whitelist name
deleted
boolean
Has whitelist been deleted, ignored in requests
rshell_variant
string
Restricted shell variant, required if command restrictions are enabled
- Enum
-
- bash
- posix
banner
string
Optional banner displayed in SSH terminal
allow_no_match
boolean
If true then commands that do not match any whitelist pattern are allowed to execute
audit_match
boolean
If true then an audit event is generated for every allowed command
audit_no_match
boolean
If true then an audit event is generated for every disallowed command
whitelists
array[object]
object
additional whitelist grant
whitelist
object (whitelist)
id
string
uuid
required
Whitelist ID
name
string
Whitelist name
deleted
boolean
Has whitelist been deleted, ignored in requests
roles
array[object]
List of roles granting access to the whitelist
object
id
string
uuid
required
Role ID
name
string
Role name
password_rotation_enabled
boolean
set, if there are accounts, in which passwords need to be rotated
password_rotation
object (password_rotation)
password rotation settings for host
access_group_id
string
uuid
Specify ID of access group, default access group will be used if ID is not specified. Access group will be checked for WinRM trust anchors if certificate validation option is set to enabled.
use_main_account
boolean
required
rotate passwords of all accounts in host through one account
operating_system
string
required
Bash for Linux, Powershell for windows for shell access
- Enum
-
- LINUX
- WINDOWS
winrm_address
string
IPv4 address or FQDN to use for winrm connections
winrm_port
int
port to use for password rotation with winrm, zero for winrm default
protocol
string
required
- Enum
-
- SSH
- WINRM
certificate_validation_options
string
required
Disable or enable password rotation certificate validation
- Enum
-
- DISABLED
- ENABLED
winrm_host_certificate_trust_anchors
string
WinRM host certificate trust anchors in PEM format
password_policy_id
string
uuid
required
password policy to be applied
script_template_id
string
uuid
required
script template to be run in host
rotation_status
array[object]
Filled by backend. Rotation status per account to be shown in UI
object
principal
string
last_rotated
string
date-time
When last successful rotation. Added by backend
- Example
- "2017-01-01T15:05:05Z"
last_error
string
date-time
Last rotation error. Cleared when rotation successful, updated by backend
- Example
- "2017-01-01T15:05:05Z"
last_error_details
string
information of rotation error, updated by backend
created
string
date-time
When the object was created. Added by backend
- Example
- "2017-01-01T15:05:05Z"
updated
string
date-time
When the object was updated. Added by backend
- Example
- "2017-01-01T15:05:05Z"
created_by
string
added by backend
updated_by
string
added by backend
source_id
string
A unique import-source identifier for the host entry, for example a hash for AWS account ID. (searchable by keyword)
cloud_provider
string
The cloud provider this host resides in
cloud_provider_region
string
The cloud provider region the host resides in
status
array[object]
object
k
string
v
string
created
string
date-time
When the object was created
- Example
- "2017-01-01T15:05:05Z"
updated
string
date-time
When the object was updated
- Example
- "2017-01-01T15:05:05Z"
updated_by
string
uuid
Id of the user who updated the object
- Example
- "eef4aefc-d64e-4c2c-aba4-4914c86ce059"
distinguished_name
string
LDAPv3 Disinguished name (searchable by keyword)
common_name
string
X.500 Common name (searchable by keyword)
organization
string
X.500 Organization (searchable by keyword)
organizational_unit
string
X.500 Organizational unit (searchable by keyword)
zone
string
Equipment zone (development, production, user acceptance testing, ..) (searchable by keyword)
scope
array[string]
Under what compliance scopes the listed equipment falls under (searchable by keyword)
string
Compliancy requirement (PCI, HIPAA, ..)
host_type
string
Equipment type (virtual, physical) (searchable by keyword)
host_classification
string
Classification (Windows desktop, Windows server, AIX, Linux RH, ..) (searchable by keyword)
comment
string
A comment describing the host
addresses
array[string]
string
Fully qualified domain names, and/or IPv4 or IPv6 addresses of the host (searchable by keyword)
tags
array[string]
string
disabled
string
- Enum
-
- BY_ADMIN
- BY_LICENSE
access_group_id
string
uuid
Defines host's access group
deployable
boolean
Whether the host is writable through /deploy end point with deployment credentials
tofu
boolean
Whether the host key should be accepted and stored on first connection
stand_alone_host
boolean
Indicates it is a standalone host - bound to local host directory
external_id
string
The equipment ID from the originating equipment store
instance_id
string
The instance ID from the originating cloud service (searchable by keyword)
audit_enabled
boolean
Wheter the host is set to be audited.
session_recording_options
object (session_recording_options)
Flags to disable trail auditing for certain features when auditing is enabled
disable_clipboard_recording
boolean
Disable clipboard trail auditing when auditing is enabled
disable_file_transfer_recording
boolean
Disable file transfer trail auditing when auditing is enabled
ssh_host_public_keys
array[object]
object
key
string
Host public key, used to verify the identity of the accessed host
host_certificate_raw
string
Host certificate, used to verify that the target host is the correct one.
contact_address
string
The host public address scanning script instructs the host store to use in service address-field.
services
array[object]
object
service
string
Allowed protocol - SSH, RDP, VNC, WEB, DB (searchable)
- Enum
-
- SSH
- RDP
- VNC
- WEB
- DB
address
string
Service address, IPv4, IPv6 or FQDN
port
int
Service port
use_for_password_rotation
boolean
if service SSH, informs whether this service is used to rotate password
- Default
- false
db
object (db)
protocol
string
Database protocol
- Enum
-
- postgres
- mysql
- passthrough
- tls
tls_certificate_validation
string
- Enum
-
- ENABLED
- DISABLED
tls_certificate_trust_anchors
string
Database server TLS certificate trust anchors in PEM
audit_skip_bytes
int
Session recording of the protocol stream will start only when this amount of bytes have been transferred from client to server. Set to zero to start session recording from start of protocol stream.
source
string
Identifies the source of the services object "UI", "SCIM" or "SCAN". Deploy is also treated as "UI".
principals
array[object]
What principals (target server user names/ accounts) the host has
object
principal
string
The account name
rotate
boolean
Rotate password of this account
use_for_password_rotation
boolean
marks account to be used as the account through which password rotation takes place, when flag use_main_account set in rotation_metadata
use_user_account
boolean
Use user account as host principal name
passphrase
string
The account static passphrase or the initial rotating password value. If rotate selected, active in create, disabled/hidden in edit
source
string
Identifies the source of the principals object "UI" or "SCAN". Deploy is also treated as "UI".
roles
array[object]
An array of roles entitled to access this principal on the host
object
id
string
uuid
Role UUID
applications
array[object]
An array of application the principal may launch on the target host
object
application the principal may launch on the target host
name
string
application
string
arguments
string
working_directory
string
service_options
object (service_options)
Object for service options
ssh
object (ssh)
SSH service options
shell
boolean
Shell channel
file_transfer
boolean
File transfer channel
exec
boolean
exec channel
tunnels
boolean
tunnels
x11
boolean
x11
other
boolean
other options
rdp
object (rdp)
RDP service options
file_transfer
boolean
file transfer
audio
boolean
audio
clipboard
boolean
clipboard
web
object (web)
WEB service options
file_transfer
boolean
file transfer
audio
boolean
audio
clipboard
boolean
clipboard
vnc
object (vnc)
VNC service options
file_transfer
boolean
file transfer
clipboard
boolean
clipboard
db
object (db)
DB service options
max_bytes_download
int
Maximum number of bytes allowed in download direction per connection. Set to zero to disable byte count limiting.
max_bytes_upload
int
Maximum number of bytes allowed in upload direction per connection. Set to zero to disable byte count limiting.
command_restrictions
object (command_restrictions)
SSH shell/exec command restrictions for the principal
enabled
boolean
Are command restrictions enabled
default_whitelist
object (default_whitelist)
Default whitelist handle, required if command restrictions are enabled
id
string
uuid
required
Whitelist ID
name
string
Whitelist name
deleted
boolean
Has whitelist been deleted, ignored in requests
rshell_variant
string
Restricted shell variant, required if command restrictions are enabled
- Enum
-
- bash
- posix
banner
string
Optional banner displayed in SSH terminal
allow_no_match
boolean
If true then commands that do not match any whitelist pattern are allowed to execute
audit_match
boolean
If true then an audit event is generated for every allowed command
audit_no_match
boolean
If true then an audit event is generated for every disallowed command
whitelists
array[object]
object
additional whitelist grant
whitelist
object (whitelist)
id
string
uuid
required
Whitelist ID
name
string
Whitelist name
deleted
boolean
Has whitelist been deleted, ignored in requests
roles
array[object]
List of roles granting access to the whitelist
object
id
string
uuid
required
Role ID
name
string
Role name
password_rotation_enabled
boolean
set, if there are accounts, in which passwords need to be rotated
password_rotation
object (password_rotation)
password rotation settings for host
access_group_id
string
uuid
Specify ID of access group, default access group will be used if ID is not specified. Access group will be checked for WinRM trust anchors if certificate validation option is set to enabled.
use_main_account
boolean
required
rotate passwords of all accounts in host through one account
operating_system
string
required
Bash for Linux, Powershell for windows for shell access
- Enum
-
- LINUX
- WINDOWS
winrm_address
string
IPv4 address or FQDN to use for winrm connections
winrm_port
int
port to use for password rotation with winrm, zero for winrm default
protocol
string
required
- Enum
-
- SSH
- WINRM
certificate_validation_options
string
required
Disable or enable password rotation certificate validation
- Enum
-
- DISABLED
- ENABLED
winrm_host_certificate_trust_anchors
string
WinRM host certificate trust anchors in PEM format
password_policy_id
string
uuid
required
password policy to be applied
script_template_id
string
uuid
required
script template to be run in host
rotation_status
array[object]
Filled by backend. Rotation status per account to be shown in UI
object
principal
string
last_rotated
string
date-time
When last successful rotation. Added by backend
- Example
- "2017-01-01T15:05:05Z"
last_error
string
date-time
Last rotation error. Cleared when rotation successful, updated by backend
- Example
- "2017-01-01T15:05:05Z"
last_error_details
string
information of rotation error, updated by backend
created
string
date-time
When the object was created. Added by backend
- Example
- "2017-01-01T15:05:05Z"
updated
string
date-time
When the object was updated. Added by backend
- Example
- "2017-01-01T15:05:05Z"
created_by
string
added by backend
updated_by
string
added by backend
source_id
string
A unique import-source identifier for the host entry, for example a hash for AWS account ID. (searchable by keyword)
cloud_provider
string
The cloud provider this host resides in
cloud_provider_region
string
The cloud provider region the host resides in
distinguished_name
string
LDAPv3 Disinguished name (searchable by keyword)
common_name
string
X.500 Common name (searchable by keyword)
organization
string
X.500 Organization (searchable by keyword)
organizational_unit
string
X.500 Organizational unit (searchable by keyword)
zone
string
Equipment zone (development, production, user acceptance testing, ..) (searchable by keyword)
scope
array[string]
Under what compliance scopes the listed equipment falls under (searchable by keyword)
string
Compliancy requirement (PCI, HIPAA, ..)
host_type
string
Equipment type (virtual, physical) (searchable by keyword)
host_classification
string
Classification (Windows desktop, Windows server, AIX, Linux RH, ..) (searchable by keyword)
comment
string
A comment describing the host
addresses
array[string]
string
Fully qualified domain names, and/or IPv4 or IPv6 addresses of the host (searchable by keyword)
tags
array[string]
string
disabled
string
- Enum
-
- BY_ADMIN
- BY_LICENSE
certificate_template
string
Name of the certificate template used for certificate authentication for this host
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
oauth
Required Scopes:
admin
hostsManage
service
Create a host to host store
All Scopes
-
admin
· Admin scope - used for built-in PrivX admin account -
hostsManage
· Clients with hosts-manage scope -
hostsProvisioning
· Deploy script users -
hostsView
· Clients with hosts-view scope -
service
· Microservice scope - used for communication between PrivX microservices -
user
· Normal users
- Flow Type:
- authorization_code
- Auth URL:
- https://api.x.com/v1/auth/auth
- Token URL:
- https://api.x.com/v1/auth/auth
Request
{
"access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
"deployable": true,
"tofu": true,
"stand_alone_host": true,
"external_id": "string",
"instance_id": "string",
"audit_enabled": true,
"session_recording_options": {
"disable_clipboard_recording": true,
"disable_file_transfer_recording": true
},
"ssh_host_public_keys": [
{
"key": "string"
}
],
"host_certificate_raw": "string",
"contact_address": "string",
"services": [
{
"service": "SSH",
"address": "string",
"port": 123,
"use_for_password_rotation": true,
"db": {
"protocol": "postgres",
"tls_certificate_validation": "ENABLED",
"tls_certificate_trust_anchors": "string",
"audit_skip_bytes": 123
},
"source": "string"
}
],
"principals": [
{
"principal": "string",
"rotate": true,
"use_for_password_rotation": true,
"use_user_account": true,
"passphrase": "string",
"source": "string",
"roles": [
{
"id": "5bf77342-221c-11ee-be56-0242ac120002"
}
],
"applications": [
{
"name": "string",
"application": "string",
"arguments": "string",
"working_directory": "string"
}
],
"service_options": {
"ssh": {
"shell": true,
"file_transfer": true,
"exec": true,
"tunnels": true,
"x11": true,
"other": true
},
"rdp": {
"file_transfer": true,
"audio": true,
"clipboard": true
},
"web": {
"file_transfer": true,
"audio": true,
"clipboard": true
},
"vnc": {
"file_transfer": true,
"clipboard": true
},
"db": {
"max_bytes_download": 123,
"max_bytes_upload": 123
}
},
"command_restrictions": {
"enabled": true,
"default_whitelist": {
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string",
"deleted": true
},
"rshell_variant": "bash",
"banner": "string",
"allow_no_match": true,
"audit_match": true,
"audit_no_match": true,
"whitelists": [
{
"whitelist": {
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string",
"deleted": true
},
"roles": [
{
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string"
}
]
}
]
}
}
],
"password_rotation_enabled": true,
"password_rotation": {
"access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
"use_main_account": true,
"operating_system": "LINUX",
"winrm_address": "string",
"winrm_port": 123,
"protocol": "SSH",
"certificate_validation_options": "DISABLED",
"winrm_host_certificate_trust_anchors": "string",
"password_policy_id": "5bf77342-221c-11ee-be56-0242ac120002",
"script_template_id": "5bf77342-221c-11ee-be56-0242ac120002",
"rotation_status": [
{
"principal": "string",
"last_rotated": "2017-01-01T15:05:05Z",
"last_error": "2017-01-01T15:05:05Z",
"last_error_details": "string"
}
],
"created": "2017-01-01T15:05:05Z",
"updated": "2017-01-01T15:05:05Z",
"created_by": "string",
"updated_by": "string"
},
"source_id": "string",
"cloud_provider": "string",
"cloud_provider_region": "string",
"distinguished_name": "string",
"common_name": "string",
"organization": "string",
"organizational_unit": "string",
"zone": "string",
"scope": [
"string"
],
"host_type": "string",
"host_classification": "string",
"comment": "string",
"addresses": [
"string"
],
"tags": [
"string"
],
"disabled": "BY_ADMIN",
"certificate_template": "string"
}
Response
Host successfully created
{
"id": "5bf77342-221c-11ee-be56-0242ac120002"
}
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
]
}
Conflict. A host uniqueness check failed. Either host externalId or existing service with duplicate contactAddress already exists in the database.
{
"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
]
}
id
string
uuid
Id of the created resource
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)
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)
recursiveservice
string
required
service type (SSH, RDP, ...)
address
string
required
service address
port
int
required
service port
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
oauth
Required Scopes:
admin
hostsView
service
Resolve service+address to a single host in host store
All Scopes
-
admin
· Admin scope - used for built-in PrivX admin account -
hostsManage
· Clients with hosts-manage scope -
hostsProvisioning
· Deploy script users -
hostsView
· Clients with hosts-view scope -
service
· Microservice scope - used for communication between PrivX microservices -
user
· Normal users
- Flow Type:
- authorization_code
- Auth URL:
- https://api.x.com/v1/auth/auth
- Token URL:
- https://api.x.com/v1/auth/auth
Request
{
"service": "string",
"address": "string",
"port": 123
}
Response
Host successfully found, if multiple hosts match the query, return 500 internal server error with relevant error codes
{
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
"deployable": true,
"tofu": true,
"stand_alone_host": true,
"external_id": "string",
"instance_id": "string",
"audit_enabled": true,
"session_recording_options": {
"disable_clipboard_recording": true,
"disable_file_transfer_recording": true
},
"ssh_host_public_keys": [
{
"key": "string",
"fingerprint": "string"
}
],
"host_certificate_raw": "string",
"host_certificate": {
"subject": "string",
"issuer": "string",
"serial": "string",
"not_before": "string",
"not_after": "string",
"dns_names": [
"string"
],
"email_addresses": [
"string"
],
"ip_addresses": [
"string"
],
"fingerprint_sha1": "string",
"fingerprint_sha256": "string"
},
"contact_address": "string",
"services": [
{
"service": "SSH",
"address": "string",
"port": 123,
"use_for_password_rotation": true,
"ssh_tunnel_port": 123,
"source": "string",
"login_page_url": "string",
"username_field_name": "string",
"password_field_name": "string",
"login_request_url": "string",
"login_request_password_property": "string",
"auth_type": "string",
"status": "OK",
"status_updated": "string",
"allowed_domains": [
"string"
],
"service_version": "string",
"use_legacy_cipher_suites": true,
"tls_min_version": "string",
"tls_max_version": "string",
"browser": "string",
"db": {
"protocol": "postgres",
"tls_certificate_validation": "ENABLED",
"tls_certificate_trust_anchors": "string",
"audit_skip_bytes": 123
},
"created": "2017-01-01T15:05:05Z",
"updated": "2017-01-01T15:05:05Z",
"certificate_template": "string"
}
],
"principals": [
{
"principal": "string",
"rotate": true,
"use_user_account": true,
"passphrase": "string",
"username_attribute": "string",
"source": "string",
"roles": [
{
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string",
"deleted": true
}
],
"applications": [
{
"name": "string",
"application": "string",
"arguments": "string",
"working_directory": "string"
}
],
"service_options": {
"ssh": {
"shell": true,
"file_transfer": true,
"exec": true,
"tunnels": true,
"x11": true,
"other": true
},
"rdp": {
"file_transfer": true,
"audio": true,
"clipboard": true
},
"web": {
"file_transfer": true,
"audio": true,
"clipboard": true
},
"vnc": {
"file_transfer": true,
"clipboard": true
},
"db": {
"max_bytes_download": 123,
"max_bytes_upload": 123
}
},
"command_restrictions": {
"enabled": true,
"default_whitelist": {
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string",
"deleted": true
},
"rshell_variant": "bash",
"banner": "string",
"allow_no_match": true,
"audit_match": true,
"audit_no_match": true,
"whitelists": [
{
"whitelist": {
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string",
"deleted": true
},
"roles": [
{
"id": "5bf77342-221c-11ee-be56-0242ac120002",
"name": "string"
}
]
}
]
}
}
],
"password_rotation_enabled": true,
"password_rotation": {
"access_group_id": "5bf77342-221c-11ee-be56-0242ac120002",
"use_main_account": true,
"operating_system": "LINUX",
"winrm_address": "string",
"winrm_port": 123,
"protocol": "SSH",
"certificate_validation_options": "DISABLED",
"winrm_host_certificate_trust_anchors": "string",
"password_policy_id": "5bf77342-221c-11ee-be56-0242ac120002",
"script_template_id": "5bf77342-221c-11ee-be56-0242ac120002",
"rotation_status": [
{
"principal": "string",
"last_rotated": "2017-01-01T15:05:05Z",
"last_error": "2017-01-01T15:05:05Z",
"last_error_details": "string"
}
],
"created": "2017-01-01T15:05:05Z",
"updated": "2017-01-01T15:05:05Z",
"created_by": "string",
"updated_by": "string"
},
"source_id": "string",
"cloud_provider": "string",
"cloud_provider_region": "string",
"status": [
{
"k": "string",
"v": "string"
}
],
"created": "2017-01-01T15:05:05Z",
"updated": "2017-01-01T15:05:05Z",
"updated_by": "eef4aefc-d64e-4c2c-aba4-4914c86ce059",
"distinguished_name": "string",
"common_name": "string",
"organization": "string",
"organizational_unit": "string",
"zone": "string",
"scope": [
"string"
],
"host_type": "string",
"host_classification": "string",
"comment": "string",
"addresses": [
"string"
],
"tags": [
"string"
],
"disabled": "BY_ADMIN"
}
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
access_group_id
string
uuid
Defines host's access group
deployable
boolean
Whether the host is writable through /deploy end point with deployment credentials
tofu
boolean
Whether the host key should be accepted and stored on first connection
stand_alone_host
boolean
Indicates it is a standalone host - bound to local host directory
external_id
string
The equipment ID from the originating equipment store
instance_id
string
The instance ID from the originating cloud service (searchable by keyword)
audit_enabled
boolean
Wheter the host is set to be audited.
session_recording_options
object (session_recording_options)
Flags to disable trail auditing for certain features when auditing is enabled
disable_clipboard_recording
boolean
Disable clipboard trail auditing when auditing is enabled
disable_file_transfer_recording
boolean
Disable file transfer trail auditing when auditing is enabled
ssh_host_public_keys
array[object]
object