users
Download SpecPrivX local and remote users and role mappings
user_id
string
required
User ID
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
OAuth2
Required Scopes:
admin
usersView
service
Get specific user & roles.
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 user info
{
"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)
recursiveid
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"
user_id
string
required
User id
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
OAuth2
Required Scopes:
admin
usersView
service
Get specific user settings.
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 user's settings
{}
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
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)
recursiveAuthorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
user_id
string
required
User id
OAuth2
Required Scopes:
admin
usersManage
service
Set specific user's settings.
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
{}
Response
Successful response.
{
"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)
recursiveid
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"
user_id
string
required
User ID
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
OAuth2
Required Scopes:
admin
rolesView
service
Get specific user's roles.
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 user's role IDs & indication if the role is explicitly granted or implicitly mapped
{
"count": 123,
"items": [
{
"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
}
]
}
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]
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
Set specific user's roles. These are granted in addition to mapped roles.
array[object]
- Content Type
- application/json
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
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
user_id
string
required
User ID
OAuth2
Required Scopes:
admin
rolesManage
service
Set specific user's roles. These are granted in addition to mapped roles.
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": "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
}
]
Response
Successful response, user 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
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)
recursiveTurn on multifactor authentication for an array of user IDs.
array[string]
- Content Type
- application/json
string
uuid
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
OAuth2
Required Scopes:
admin
usersManage
service
Turn on multifactor authentication for an array of user 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
[
"5bf77342-221c-11ee-be56-0242ac120002"
]
Response
Successful response, MFA turned on for the requested user IDs
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
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)
recursiveTurn off multifactor authentication for an array of user IDs
array[string]
- Content Type
- application/json
string
uuid
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
OAuth2
Required Scopes:
admin
usersManage
service
Turn off multifactor authentication for an array of user 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
[
"5bf77342-221c-11ee-be56-0242ac120002"
]
Response
Successful response, MFA turned off for the requested user IDs
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
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)
recursivearray[string]
- Content Type
- application/json
string
uuid
Authorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
OAuth2
Required Scopes:
admin
usersManage
service
Reset multifactor authentication for an array of user 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
[
"5bf77342-221c-11ee-be56-0242ac120002"
]
Response
Successful response, MFA turned to uninitialized state for the requested user IDs
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
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)
recursiveAuthorization
string
required
OAuth2 token
- Default
- "Bearer a-proper-token-goes-here"
OAuth2
Required Scopes:
user
admin
service
Get current user and user's settings.
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 the user.
{
"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"