API Functions
Common / Security
API key permissions
Almost all API functions require Advanced API permissions on API key to be checked and a precise list of rights to be selected. An API call that does not require this option has a note "Does not require Advanced API permissions."
Advanced API permissions allow to address the power of the API key for exact API functions. Whenever the Advanced API permissions option is selected, the permissions are checked within the API call, even if the API call does not require this access level.
Each API function has the "Permission info" note, where the list of required permissions is mentioned.
When the user token is used within the API call, the API key used for login has to match the API key used for the API call. The user token contains the user permissions that must match the "Permission info" note in each API call. For API calls whose descriptions do not contain a note "Does not require Advanced API permissions.", the "Advanced API permissions" of the used API key must correspond to the permissions listed in the "Permission info" note in each API call.
Security
We highly recommend you to use this option and select only the necessary permissions for each API key.Authorization: Bearer <user_token>
.
Version
Get server version
Permission info
Does not require Advanced API permissions.
Path: /version
- Method:
GET
- Parameters: none
- Returns:
ServerVersionInfo
ord print/copy/scan jobs:
- Errors: 403
Account
Get account information
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewAccount permission.
Does not require Advanced API permissions.
- Path:
/account
- Method:
GET
,HEAD
- Parameters:
domainname: string
optional domain name. If not specified, the request address is used - Returns:
AccountInfo
for GET request, empty 200 status for HEAD request - Errors: 404
- Notes: For
HEAD
request the X-API-Key header is not required
Create account
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewAccount and CreateAccount permissions.
- Path:
/account
- Method:
PUT
- Parameters:
parentdomain: string
The domain name of the parent accountaccountname: string
Name of the accountaccounttype: int
Type of the account: 1 = vendor, 2 = customer, 3 = containerdomainname: string
Account domain name. This parameter can be specified more than once. The domain name can contain letters, numbers, hyphens, and periods. Any part of the domain name (separated by a period) should begin and end with a letter or number.applicationname: string
Account application name- [optional]
trustallclients: bool
Automatically trust the account value - [optional]
locationid: int
Id of the existing location to be assigned to the created account
- Returns:
ErrorCodeInfoId
cURL example:
#!/bin/sh
`curl -X PUT -i -v -H "X-Api-Key:" -d "parentdomain=" -d "accountname=" -d "accounttype=" -d "domainname=" -d "domainname=" -d "applicationname=" -d "trustallclients=" -d "locationid=" -k "https://:7300/api/v1/account"`
Replace all with real values.
Update account
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewAccount and ModifyAccount permissions.
- Path:
/account
- Method:
PATCH
- Parameters:
- [optional]
accountname: string
Name of the account - [optional]
domainname: string
Account domain name. This parameter can be specified more than once
A domain name can contain letters, numbers, hyphens, and periods. Any part of the domain name (separated by a period) should begin and end with a letter or number. - [optional]
applicationname
:string
Account application name - [optional]
trustallclients: string
Automatically trust the account value - [optional]
locationid: string
Id of the existing location to be assigned to the created account - [optional]
locale: string
Account's language - expected values: "pt-BR" (Brazilian Portuguese), "zh" (Chinese), "cs" (Czech), "da" (Danish), "nl" (Dutch), "en" (English), "fr" (French), "de" (German), "id" (Indonesian), "it" (Italian), "ja" (Japanese), "ko" (Korean), "ms" (Malay), "no" (Norwegian), "pl" (Polish), "pt" (Portuguese), "sk" (Slovak), "es" (Spanish), "sv" (Swedish), "th" (Thai) - [optional]
defaultpapersize: string
Account's default paper size - expected values: "A3", "A4", "A5", "Letter" - [optional]
theme: string
Account's color theme - expected values: "blue", "orange", "purple", "red", "green", "breeze"
- [optional]
- Returns:
ErrorCodeInfoId
cURL example:
curl -X PATCH "https://server_name:7300/api/v1/account" -H "X-Api-Key: key" -d "accountname=" -d "domainname=" -d "applicationname=" -d "trustallclients=" -d "locationid=" -d "locale=" -d "defaultpapersize=" -d "theme="
Get containers
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewAccount permission.
- Path:
/account/containers
- Method:
GET
- Parameters: None
- Returns: list of
ContainerInfo
- Errors: 403
cURL example:
curl -X GET -H "X-Api-Key: advanced_api_permissions_key" -k "https://server_name:7300/api/v1/account/containers"
Update container
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewAccount and ModifyAccount permissions.
- Path:
/account/container/*id*
- Method:
PUT
- Parameters:
domainname: string
Container domain name. This parameter can be specified more than oncecontainername: string
Name of the container- [optional]
applicationname: string
Container application name - [optional]
locationid: int
Id of the existing location to be assigned to the container
- Returns:
ErrorCodeInfoId
- Errors: 403, 404
cURL example:
curl -X PUT -H "X-Api-Key: advanced_api_permissions_key" -k "https://server_name:7300/api/v1/account/container/CONTAINER_ID" -d domainname= -d domainname= -d containername= -d applicationname= -d locationid=
Replace all CONTAINER_ID
with real value.
Delete container
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewAccount and DeleteAccount permissions.
- Path:
/account/container/*id*
- Method:
DELETE
- Parameters:
- [optional query parameter]
withsubnodes: boolean
true/false, whether to delete the non-empty container
- [optional query parameter]
- Returns:
ErrorCodeInfoId
- Errors: 403, 404
cURL example:
curl -X DELETE -H "X-Api-Key: advanced_api_permissions_key" -k "https://server_name:7300/api/v1/account/container/CONTAINER_ID?withsubnodes=true"
Replace all CONTAINER_ID
with real value.
Login
User authentication
Permission info
Does not require Advanced API permissions.
Authorization with a device token or allowing untrusted endpoints is required .
Path: /login
- Method:
POST
- Parameters:
authtype: integer
0=password, 1=cardid, 2=shortid, 3=nameonly, 4=emailuserid: string
the id to authenticatepassword: string
an optional secret (required for authtype=0, optional for authtype=1, ignored for other types)
- Returns:
UserInfo
- Errors: 401, 403
cURL example:
#!/bin/sh
curl -X POST -H "X-Api-Key: key" -d "authtype=0" -d "userid=username" -d "password=password" "https://serveraddress:7300/api/v1/login"
Documents
Authorization: Bearer <device_token>
Get list of documents for user
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewJob permission.
Does not require Advanced API permissions.
Authorization with user token is required. Cannot call with an insecure API key.
- Path:
/documents
- Method:
GET
- Parameters:
- [optional]
status: list[int]
Status list for the documents. If not provided 0 => READY will be used. 0 => READY,1 => PRINTED, 2 => DELETED, 3 => EXPIRED, 4 => FAILED, 5 => RECEIVED, 6 => AWAITING_CONVERSION, 7 => CONVERTING, 8 => CONVERSION_FAILED, 9 => STORED - [optional]
maxRecords: int
The number of records to be retrieved. If not provided, 50 is the default value. Max value 500
- [optional]
- Returns:
list
ofDocumentInfo
- Errors: 403
Get documents’ history
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewReport permission.
Restriction info
Only available for Customer account type. It is not possible to call this on Vendor or Container account types. In such case, the call returns a 400 error.
This endpoint is designed to get raw document data for building custom dashboards. Since the output can potentially be very large, the endpoint is equipped with paging functionality.
- Path:
/documents/history
- Method:
GET
- Parameters:
- [optional]
maxrecords: int
Maximum number of records on the single response page. The default value is 200, maximum is 2000. - [optional]
pagetoken: string
If the number or records for your query exceedsmaxrecords
value, the endpoint responds with exactlymaxrecords
documents and non-emptynextPageToken
field. Use value ofnextPageToken
as apagetoken
parameter to get the next page. - [optional]
datestart: datetime
ISO-8601 instant formatted start point for documents’ creation dates range. Example:2021-09-21T16:38:10.972Z
- [optional]
dateend: datetime
ISO-8601 instant formatted endpoint for documents’ creation dates range. The maximum allowed timeframe is 1 week.datestart
should be less thandateend
, and the latter should be in the future. The default value is “last 24 hours”. - [optional]
domainname: string
If you want to narrow the request scope to one of your accounts, you can provide its domain name. Queried account should be a sub-account related to the account you are querying. When this parameter is not provided, the query is made against the account that has domain, taken from URL and all its subdomains. - [optional]
username: string
The exact login name of the user for which you want data to be delivered. When not specified, no filtering takes place. - [optional]
portname: string
The exact name of the port where the document was printed. When not specified, no filtering takes place. - [optional]
status:
list[int]
Status list for the documents. When not specified, no filtering takes place. 0 => READY,1 => PRINTED, 2 => DELETED, 3 => EXPIRED, 4 => FAILED, 5 => RECEIVED, 6 => AWAITING_CONVERSION, 7 => CONVERTING, 8 => CONVERSION_FAILED, 9 => STORED - [optional]
jobtype: string Document job type (PRINT, COPY, SCAN, FAX)
- [optional]
Returns:
documents
: array ofDocumentInfo
recordsOnPage: Integer
nextPageToken: String
dateStart: String
dateEnd: String
domainName: String
userName: String
portName: String
DocumentInfo
:
providerId: Int
uuid: String
documentName: String
documentType: Int
userName: String
totalPages: Int
colorPages: Int
duplex: Int
copies: Int
grayscale: Boolean
paperSize: String
dateTime: Long
storageOnline: Boolean
secure: Boolean
tags:
list ofTagInfo
collate: Boolean
status: I
nt
Type of Status: 0 => READY,1 => PRINTED, 2 => DELETED, 3 => EXPIRED, 4 => FAILED, 5 => RECEIVED, 6 => AWAITING_CONVERSION, 7 => CONVERTING, 8 => CONVERSION_FAILED, 9 => STORED-
outputPortId
:I
nt
-
outputPortName
:String
-
jobType: String
(PRINT, COPY, SCAN, FAX)
TagInfo
tagType: int
Type of Tag: 0 = Department, 1 = Groupname: String
Tag name
Errors: 400
Usage example:
Example request
curl --request GET 'https://yourhost:7300/api/v1/documents/history?datestart=2021-09-07T16:38:10.972Z&dateend=2021-09-10T16:38:10.972Z&domainname=testaccount1&username=admin&maxrecords=2' \
--header 'X-Api-Key: advanced_api_permissions_key' \
Example response
{
"documents": [
{
"providerId": 65,
"uuid": "1b83f9ca-a05b-44cf-8c0b-ae7b4c934f92",
"documentName": "Importand document 12345",
"documentType": 0,
"userName": "admin",
"totalPages": 0,
"colorPages": 0,
"duplex": 0,
"copies": 1,
"grayscale": false,
"paperSize": "",
"dateTime": 1631205678743,
"storageOnline": false,
"tags": [
{
"tagType": 0,
"name": "dev dep"
},
{
"tagType": 1,
"name": "dev"
},
{
"tagType": 1,
"name": "devsupport"
}
],
"collate": false,
"status": 1,
"outputPortId": 1,
"outputPortName" "Test printer",
"jobType": "PRINT"
},
...
],
"recordsOnPage": 2,
"nextPageToken": "8a63ee56-3d9e-404f-a131-86b3bf9025b8",
"dateStart": "2021-09-07T16:38:10.972Z",
"dateEnd": "2021-09-10T16:38:10.972Z",
"domainName": "testaccount1",
"userName": "admin",
"portName": ""
}
Presence of the nextPageToken
means that there’s more data than you received on this page and you have to query next portion like the following:
curl --location --request GET 'https://yourhost:7300/api/v1/documents/history?pagetoken=8a63ee56-3d9e-404f-a131-86b3bf9025b8' \
--header 'X-Api-Key: advanced_api_permissions_key' \
Repeat paging until returned nextPageToken
becomes blank.
Record print/copy/scan jobs:
The request can be authentication either by using a device token or a user token.
- If you want to use a user token, the user for the job record is taken from the user token.
- If you want to use a device token, the user for the job record is taken from the required parameters "username" and "providerid".
In any case, the request requires API key configured with an authenticated request or a trusted endpoint.
- Path:
/documents/history
- Method:
POST
- Parameters:
- [required]
jobtype: String
Document job type:PRINT, COPY, SCAN, FAX.
- [optional]
totalpages: String
Total pages of the document. - [optional]
colorpages: String
Color pages of the document. - [optional]
papersize: String
Size of document paper. - [optional]
duplex: Boolean
Types of duplex printing: If true use LONG otherwiseSHORT
. - [optional]
title: String
Title of the document. - [optional]
serialnumber: String
Serial number to find output port. - [optional]
address: String
Address to find output port. - [optional]
username: String
User name, if you use a device token. - [optional]
providerid: String
Authentication provider identifier, if you use a device token.
- [required]
Returns: 200 Success
Errors: 400, 401, 403
Example request:
curl -i -X POST -H "X-Api-Key:" -H "Authorization:" -d "jobtype=PRINT" "https://:7300/api/v1/documents/history"
Upload document
Permission info
If you provide a user token, make sure the user for whom the token was issued has the AddJob permission.
Does not require Advanced API permissions.
- Path:
/documents
- Method:
PUT
- Parameters (multipart/form-data request):
- [optional]
providerid: int
The ID of the authentication provider for the given user. If not provided or zero, the server will attempt to guess it. data: form-data
A multipart form parameter with Content-Disposition: form-data; name=“data”; filename=“xxx” header and
content typeapplication/octet-stream
username: string
Name of the userportname: string
Name of the input port (queue)title: string
Document title- [optional]
copies: string
Number of copies - [optional]
grayscale: string
Should print grayscale true/false - [optional]
duplex: string
Duplex flag: 0=simplex, 1=long edge, 2=short edge - [optional]
outputpagesize
: string
Output page size ("Original", "A3", "A4", "A5", "A6", "Letter", "Legal", "Ledger", "Tabloid" or custom "<Width>x<Height>" width and height in points - for example for A4 "595x842") - [optional]
pageorientation
: string
Page orientation: 0 = portrait, 1 = landscape (Note: Some page output page sizes do not support page orientation - like Ledger or Tabloid.) - [optional]
scale
: string
Scale in percent (1-100)
- [optional]
- Returns:
DocumentInfo
- Errors: 400, 403
cURL example:
curl -X PUT -i -v -H "X-Api-Key: " -F "username=" -F "portname=" -F "title=" -F "data=@;filename=" -k https://:7300/api/v1/documents
Replace all with real values.
The “@” symbol in -F "data="
is mandatory.
If the extension of the ‘filename’ is different than pdf, please make sure that you include that extension to the ‘title’ parameter.
For example, if the filename=file.docx, the title should be test.docx.
Limitations for uploading MS Office files:
- The maximum document size the user can upload is 200 MB.
- Print preview of one Microsoft Excel file can contain at most 10 thousand pages.
- The duration of conversion from MS Office files to PDF is limited to 5 minutes.
If the user exceeds any of these limitations, it will result in conversion failure.
Parameters outputpagesize, pageorientation, scale are supported only using the push print (when job is sent directly to the printer).
With pull print (when job is downloaded on MFD and printed) these parameters are ignored.
Delete document
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewJob and DeleteJob permissions.
Does not require Advanced API permissions for a user who owns the document.
- Path:
/documents/
- Method: DELETE
- Parameters:
uuid: pathparam
Document UUID taken from the request path
- Returns:
ErrorCodeInfo
- Errors: 403
Send document to output port
Permission info
If you provide a user token, make sure the user for whom the token was issued has ReleaseJob permission.
Does not require Advanced API permissions for a user who owns the document.
An insecure API key is not allowed for this request.
- Path:
/documents/uuid/<address or SN>
- Method: POST
- Parameters:
uuid: pathparam
Document UUIDaddress: pathparam
Output port addressSN
:pathparam
Output port serial numbercopies: int
Number of copies requestedgrayscale: bool
Whether to output in grayscale (true/false)retain: bool
Whether to keep the document after printing (true/false), default is falseduplex: int
Duplex flag: 0=simplex, 1=long edge, 2=short edge
- Returns:
ErrorCodeInfo
- Errors: 400, 403
Content
Content-type application/x-www-form-urlencoded has to be specified even when no additional parameters are specified.
Download document
Permission info
If you provide a user token, make sure the user, for whom the token was issued, has ViewJob permission.
Does not require Advanced API permissions for a user who owns the document.
Insecure API key is not allowed for this request.
- Path:
/documents/uuid.content
- Method: GET
- Parameters:
uuid: pathparam
Document UUIDcopies: int
Number of copies requestedgrayscale: bool
Whether to output in grayscale (true/false)retain: bool
Whether to keep the document after printing (true/false), default is falseduplex: int
Duplex flag: 0=simplex, 1=long edge, 2=short edge
- Returns: 200 Success
- Errors: 400, 403, 404, 503
Output Ports
Get list of output ports for user
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort permission.
- Path:
/outputports
- Method:
GET
- Parameters:
- [optional]
providerid: int
The ID of the authentication provider for the given user. If not provided or zero, the server will attempt to guess it. - [optional]
username: string
name of the user for which the ports will be retrieved
- [optional]
- Returns:
list
- Errors: 403
Create output port
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort and CreateOutputPort permissions.
- Path:
/outputports
- Method:
PUT
- Parameters:
domainname: string
Domain name of the parent accountportname: string
Name of the portaddress: string
Port addressporttype: int
Port type: 0 = dummy, 1 = printer- [optional]
serviceid: int
Id of the service (document output or terminal service) which this port will use. This parameter can be specified multiple times. - [optional]
vendor: string
Short name of the printer vendor (unknown, fujifilm, ricoh, km, sharp, hp, lexmark, xerox, kyocera, toshiba, canon, brother, epson, eop) - [optional]
embedded: bool
Whether this printer has embedded client (true/false) - [optional]
printprotocol: int
Printing protocol: 0 = tcp, 1 = ipp, 2 = spooler (CUPS) - [optional]
outputtype: int
Output type: 0 = raw, 1 = PDF, 3 = PCL6, 4 = Postscript level 3, 5 = Postscript level 2. The value of 2 is deprecated and should not be used. - [optional]
reversefinisher: bool
Whether this printer has a finisher with reversed path (true/false) - [optional]
printerippurl: string
Printer IPP URL - [optional]
modelfamily: int
printer model family: if PrinterVendor is RICOH => 0 = “Ricoh SDK/J” ;1 -> “Ricoh SOP” | if PrinterVendor is XEROX => 0 = “WorkCentre”; 1 = “AltaLink”; 2 = “VersaLink” - [optional]
monochromeprinter: bool
Monochrome printer (true/false) - [optional]
ipreaderaddress: string
IP Reader address - [optional]
embeddedconfiguration: int
Id of Embedded configuration - [optional]
deviceserial: string
IP Reader address - [optional]
matchinginputport: bool
If true, a matching input port is automatically created (true/false) - [optional]
description: string
Port description
- Returns:
ErrorCodeInfoId
curl example:
curl -X PUT -i -H "X-Api-Key:" -k "https://account-domain-name:7300/api/v1/outputports" -d domainname= -d portname= -d address= -d porttype= -d ipreaderaddress= -d deviceserial= -d reversefinisher= -d printerippurl= -d modelfamily= -d monochromeprinter= -d embeddedconfiguration= -d description=
Replace all with real values.
Update output port
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort and ModifyOutputPort permissions.
- Path:
/outputports
- Method:
PUT
- Parameters:
id: int
Existing output port id- same parameters as for “Create output port”
- Returns:
ErrorCodeInfoId
curl example:
curl -X PUT -i -H "X-Api-Key:" -k "https://account-domain-name:7300/api/v1/outputports" -d domainname= -d portname= -d address= -d porttype= -d ipreaderaddress= -d deviceserial= -d reversefinisher= -d printerippurl= -d modelfamily= -d monochromeprinter= -d embeddedconfiguration= -d description= -d id=
Replace all with real values.
Move output port
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort and ModifyOutputPort permissions.
- Path:
/outputports/<outputportid>/move
- Method:
PUT
- Parameters:
outputportid: pathparam
Existing output port iddomainname: string
Domain name of the parent accountdestinationdomainname: string
Specifies the domain name of the target account or container where the output port will be moved in the tree
- Returns:
ErrorCodeInfoId
curl example:
curl -X PUT -i -H "X-Api-Key:" -k "https://account-domain-name:7300/api/v1/outputports/<outputportid>/move" -d domainname= -d destinationdomainname
Replace all with real values.
The output port can only be moved within the same parent account and cannot be transferred outside of its current account hierarchy.
Delete output port
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewOutputPort and DeleteOutputPort permissions.
- Path:
/outputports/
- Method: DELETE
- Parameters:
outputportid: pathparam
Id of the output port to delete
- Returns:
ErrorCodeInfo
- Errors: 403
Input Ports
Create input port
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewInputPort and CreateInputPort permissions.
- Path:
/inputports
- Method:
PUT
- Parameters:
domainname: string
Domain name of the parent accountportname: string
Name of the portporttype: int
Port type: 0 = Pull queue, 1 = Push queue- [optional]
outputportid: int
Id of the mapped output port for push queue types - [optional]
portFlags: long
flags of the input port. Each bit from the long value represents a flag. Flags: AvailableByDefault: …000001 (long value 1) – enabled and …000000 (long value 0) – disabled. - [optional]
locationid: id
Id of the existing location to be assigned to the created input port
- Returns:
ErrorCodeInfoId
curl example:
curl -X PUT -H "X-Api-Key: advanced_api_permissions_key" -k "https://server_name:7300/api/v1/inputports" -d domainname= -d portname= -d porttype= -d outputportid= -d locationid=
Replace all with real values.
Update input port
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewInputPort and ModifyInputPort permissions.
- Path:
/inputports
- Method:
PUT
- Parameters:
id: int
Existing input port id- same parameters as for “Create input port”
- Returns:
ErrorCodeInfoId
curl example:
curl -X PUT -H "X-Api-Key: advanced_api_permissions_key" -k "https://server_name:7300/api/v1/inputports" -d domainname= -d portname= -d porttype= -d outputportid= -d locationid= -d id=
Replace all with real values.
Get list of input ports for user
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewInputPort permission.
Does not require Advanced API permissions.
- Path:
/inputports
- Method:
GET
- Parameters:
- [optional]
providerid: int
The ID of the authentication provider for the given user. If not provided or zero, the server will attempt to guess it. - [optional]
username: string
name of the user for which the ports will be retrieved - [optional]
locationids: int
location id. This parameter can be specified more than once.
- [optional]
- Returns:
list
- Errors: 403
Delete input port
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewInputPort and DeleteInputPort permissions.
- Path:
/inputports/
- Method: DELETE
- Parameters:
inputportid: pathparam
Id of the input port to delete
- Returns:
ErrorCodeInfo
- Errors: 403
Users
Get user information
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewUser permission.- Path:
/users
- Method:
GET
- Parameters:
-
username: string
Name of the user -
providerid
: int
Identifier of the authentication provider to which the user belongs.
-
- Returns:
UserInfo
- Errors: 403, 404
Curl example:
curl -X GET -i -H X-Api-Key: -k https://account-domain-name:7300/api/v1/users?username=john.doe&providerid=3
Create user
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewUser and CreateUser permissions.
- Path:
/users
- Method:
PUT
- Parameters:
username: string
Name of the user- [optional]
providerid
: int
Identifier of the authentication provider under which the user will be created. If the providerid is not specified, the user will be created under a local provider. - [optional]
detailtype: int
Type of the user detail to add: 0=full name, 1=email, 2=homefolder, 3=password, 4=cardid, 5=shortid, 6=pin, 7=alias, 11=department, 12=expiration, 14=externalid - [optional]
detaildata: string
Detail data.detailtype
anddetaildata
can be repeated multiple times
- Returns:
ErrorCodeInfo
- Errors: 403
curl example:
curl -X PUT -i -H X-Api-Key: -d username=john.doe -d detailtype=3 -d detaildata=password1 -d detailtype=1 -d detaildata=john.doe@cool.com -k https://account-domain-name:7300/api/v1/users
curl -X PUT -i -H X-Api-Key: -d username=john.doe -d providerid=129 -d detailtype=3 -d detaildata=password1 -d detailtype=1 -d detaildata=john.doe@cool.com -k https://account-domain-name:7300/api/v1/users
Delete user
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewUser and DeleteUser permissions.
- Path:
/users/<username>
- Method: DELETE
- Parameters:
username: pathparam
Name of the user to delete- [optional query parameter]
providerid
: int
Identifier of the authentication provider of the user who will be deleted. Users with the same username but different authentication providers will not be deleted. If the providerid is not specified, the user with the given username will be deleted from the local provider.
- Returns:
ErrorCodeInfo
- Errors: 403
curl example:
curl -X DELETE -i -H X-Api-Key: -k https://account-domain-name:7300/api/v1/users/john.doe
curl -X DELETE -i -H X-Api-Key: -k https://account-domain-name:7300/api/v1/users/john.doe?providerid=129
Update user details
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewUser, ModifyUser, GenerateShortID, GenerateOTP, and CardManagement permissions.
GenerateShortID, GenerateOTP, or CardManagement permissions are required only when the Short ID, One time password, or Card number is updated. If you do not change any of these values, none of these permissions is required.
- Path:
/users/<username>
- Method: POST
- Parameters:
username: pathparam
Name of the user to update- [optional]
providerid
: int
Identifier of the authentication provider where the user will be searched for. If the providerid is not specified, the user will be searched for in a local provider. detailtype: int
Type of the user detail to update: 0=full name, 1=email, 2=homefolder, 3=password, 4=cardid, 5=shortid, 6=pin, 7=alias, 11=department, 12=expiration, 14=externalid- [optional]
detaildata: string
Detail data. If not specified, the given detail is deleted from the user. An alias can be specified with “#PID” suffix where PID is a provider ID, for example: “user@domain.com#1234” - Note that this API call can update only one user detail. If multiple details are provided, only the first will be updated.
- Returns:
ErrorCodeInfo
- Errors: 403
curl example:
curl -X POST -i -H X-Api-Key: -d detailtype=3 -d detaildata=password1 -k https://account-domain-name:7300/api/v1/users/john.doe
curl -X POST -i -H X-Api-Key: -d providerid=129 -d detailtype=3 -d detaildata=password1 -k https://account-domain-name:7300/api/v1/users/john.doe
Import users from csv
Permission info
If you provide a user token, make sure the user for whom the token was issued has CreateUser and ModifyUser permissions.
- Path:
/users/import
- Method:
POST
- Parameters:
data: file
Csv file in format: username;firstname;lastname;mail;usergroupgroup: string
Name of the local group where the users will be importedmapping: string
Fields mapping in csv file (ex: userName:0,firstName:1,lastName:2,email:3,group:4)- [optional]
separator: string
Field separator in file (The default value is ‘,’) - [optional]
hasheader: boolean
Check if the first row is a header inside the file (The default value is false) - [optional]
async: string
Check if you wish to wait for the synchronization to be finished (The default value is false)
- Returns:
ErrorCodeInfo
- Errors: 400
curl example:
curl -X POST -i -H X-Api-Key: --form-string "separator=;" -F "mapping=userName:0,firstName:1,lastName:2,email:3,group:4" -F "hasheader=false" -F "group=" -F"data=@" -k https://account-domain-name:7300/api/v1/users/import
Register card for user
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewUser, ModifyUser, and CardManagement permissions.
Does not require Advanced API permissions.
- Path:
/users/<username>/cards
- Method: POST
- Parameters:
username: pathparam
Name of the user to whom the card is registeredcardid: string
The ID of the registered card
- Returns:
ErrorCodeInfo
- Errors: 400, 403
curl -X POST -H "X-Api-Key: " -H "Authorization: " -k "https://:7300/api/v1/users/<username>/cards" -d cardid=
Get list of groups for a given local user
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewUser permission.
- Path:
/users/USERNAME/groups
- Method:
GET
- Parameters:
USERNAME: pathparam
path parameter which contains local user name; specify user name (case insensitive) between two slashes in the path, e.g. for TestUser:/users/testuser/groups
- Returns:
list
- Errors: 400
cURL example:
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/users//groups"
curl -X GET -i -H 'X-Api-Key:46405b18-8e1b-4db9-b930-bedd9ae839af' -k https://Dispatcher Paragon Cloud1.test.local:7300/api/v1/users/mytestuser/groups
Add local user to a list of provided groups
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewUser and ModifyUser permissions.
- Path:
/users/USERNAME/groups
- Method:
PUT
- Parameters:
USERNAME: pathparam
path parameter which contains local user name; specify user name (case insensitive) between two slashes in the path, e.g. for TestUser:/users/testuser/groups
groupid: string
one or more group IDs to which this user must be added. Each ID can be either a group primary key or a textual group ID.
- Returns:
ErrorCodeInfo
- Errors: 400
cURL example:
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/users//groups" -d groupid=
Set local user membership to a list of provided groups
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewUser and ModifyUser permissions.
- Path:
/users/USERNAME/groups
- Method:
POST
- Parameters:
USERNAME: pathparam
path parameter which contains local user name; specify user name (case insensitive) between two slashes in the path, e.g. for TestUser:/users/testuser/groups
groupid: string
zero or more group IDs, which will be set as user groups. The current groups will be removed from the user. Each ID can be either a group primary key or a textual group ID. If this parameter is not provided, all groups will be cleared.
- Returns:
ErrorCodeInfo
- Errors: 400
Delete groups from user’s membership
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewUser and ModifyUser permissions.
- Path:
/users/USERNAME/groups
- Method:
DELETE
- Parameters:
USERNAME: pathparam
path parameter which contains local user name; specify user name (case insensitive) between two slashes in the path, e.g. for TestUser:/users/testuser/groups
groupid: string
one or more group IDs to delete from the user’s membership. Each ID can be either a group primary key or a textual group ID.
- Returns:
ErrorCodeInfo
- Errors: 400
cURL example:
curl -X DELETE -i -H "X-Api-Key: " -k "https://:7300/api/v1/users//groups" -d groupid=
Authentication provider
Get authentication provider
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewSecurity permission.
- Path:
/authproviders
- Method: GET
- Parameters:
accountid=
The ID of Dispatcher Paragon Cloud account domain- [optional] none
- Returns:
AuthenticationProvidersInfo
- Errors: 400
- Can be called without X-Api-Key. In this case, it will only return providers without any client/web secrets
Bash script example:
#!/bin/sh
ACCOUNT_INFO=`curl -X GET -H "X-Api-Key:" -k https://:7300/api/v1/account`
echo "$ACCOUNT_INFO"
ACCOUNT_INFO_SED=$(echo "$ACCOUNT_INFO" | sed -E 's/.*"id":\s*(\S+)(,|}|\s).*/\1/g')
echo "$ACCOUNT_INFO_SED"
ACCOUNT_ID=$(echo "$ACCOUNT_INFO_SED" | cut -f1 -d ',')
echo "$ACCOUNT_ID"
LDAP_AUTH=`curl -X GET -i -H "" -k https://:7300/api/v1/authproviders?accountid="$ACCOUNT_ID"`
echo "$LDAP_AUTH"
Replace all with real values.
Add authentication provider
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewSecurity and ManageSecurity permissions.
- Path:
/authproviders
- Method: PUT
- Parameters:
-d
parameters include:- [name] – Name of authentication provider
- [providerType] – 0 (local)/1 (LDAP)/2 (Microsoft Entra ID)/3 (okta)
- [typeConfiguration] – authentication provider configuration details. For example, for local provider, it is
{}
- [accountID] – The ID of Dispatcher Paragon Cloud account domain
- [priority] – default value is 0
- [active] – true (authentication provider is active) / false (authentication provider is inactive)
- [domainNames] – list of authorization provider domains
- [id] – defaults as 0
- [optional] none
- Returns:
ResponseCodeInfo
- Errors: 400
Bash script example to add an LDAP authentication provider:
#!/bin/sh
ACCOUNT_INFO=`curl -X GET -H "X-Api-Key:" -k https://:7300/api/v1/account`
echo "$ACCOUNT_INFO"
ACCOUNT_INFO_SED=$(echo "$ACCOUNT_INFO" | sed -E 's/.*"id":\s*(\S+)(,|}|\s).*/\1/g')
echo "$ACCOUNT_INFO_SED"
ACCOUNT_ID=$(echo "$ACCOUNT_INFO_SED" | cut -f1 -d ',')
echo "$ACCOUNT_ID"
LDAP_AUTH=`curl -X PUT -i -H "X-Api-Key:" -k https://:7300/api/v1/authproviders -d '{"name":"","providerType":1,"typeConfiguration":"{\"baseDN\":\"\",\"groupBaseDN\":\"\",\"address\":\"\",\"port\":389,\"ssl\":true,\"userName\":\"\",\"password\":\"\",\"active\":true,\"bindType\":0,\"searchMode\":0,\"userNameAttr\":\"\",\"fullNameAttr\":\"\",\"emailAttr\":\"\",\"cardId1Attr\":\"\",\"cardId2Attr\":\"\",\"shortIdAttr\":\"\",\"aliasAttr\":\"\",\"homeFolderAttr\":\"\",\"userAttrClass\":\"\",\"groupAttrClass\":\"\",\"nonEmptyAttrs\":[\"\",\"\",\"\",\"\",\"\",\"\",\"\",\"\"]}","accountId":'"$ACCOUNT_ID"',"priority":0,"active":true,"domainNames":["acme.com"],"id":0}'`
echo "$LDAP_AUTH"
Replace all with real values.
Delete authentication provider
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewSecurity and ManageSecurity permissions.
- Path:
/authproviders/
- Method: DELETE
- Parameters: none
- [optional] none
- Returns:
ResponseCodeInfo
- Errors: 400
bash script example:
#!/bin/sh
LDAP_AUTH=`curl -X DELETE -i -v -H "" -k https://:7300/api/v1/authproviders/`
echo "$LDAP_AUTH"
Replace all with real values.
Access controls
Availability on secondary/gateway servers
All access controls endpoints work on primary servers only. If you call these endpoints on secondary/gateway server, you will receive status code 400 Bad Request.
Get access control details
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewSecurity permission.
- Path:
/accesscontrols
- Method: GET
- Parameters:
accountdomain=
DNS name of account domain- [optional]
permissionsdomain=
DNS name of the account’s parent domain. By specifying this parameter, you will get access controls for the account domain, but defined at the parent domain level.
- Returns:
AccessControlsInfo
- Errors: 400
bash script example:
#!/bin/sh
ACCESS_INFO=`curl -X GET -i -H "X-Api-Key:" -k https://:7300/api/v1/accesscontrols?accountdomain=`
echo "$ACCESS_INFO"
Replace all with real values.
Add access control
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewSecurity and ManageSecurity permissions.
- Path:
/accesscontrols
- Method: PUT
- Parameters:
accountdomain=
DNS name of account domain--data
parameters include:- [authProviderId] – ID of the authentication provider for which access control is being added.
- [roleName] – choose one based on scope – Administrators/Users/Reporting/Support
- [userName] – use this parameter if assigning access control to the user directly (see note below)
- [groupName] – use this parameter if assigning access control to the group directly (see note below)
- [groupDn] – DN configuration of group/user
- [optional] none
- Returns:
ResponseCodeInfo
- Errors: 400
Note – Depending on whether you are assigning access control to a user or a group, use “userName” or “groupName” parameter, but not both at the same time
bash script example to add access control for an LDAP group as Administrators in Dispatcher Paragon Cloud:
#!/bin/sh
ACCESS_INFO=`curl -X PUT -i -H "" -k https://:7300/api/v1/accesscontrols?accountdomain= --data '{"authProviderId":,"roleName":"Administrators","groupName":"","groupDn":""}'`
echo "$ACCESS_INFO"
Replace all with real values.
Delete access control by id
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewSecurity and ManageSecurity permissions.
- Path:
/accesscontrols/*id*
- Method: DELETE
- Parameters:
accountdomain=
DNS name of account domain- [optional] none
- Returns:
ResponseCodeInfo
- Errors: 400
bash script example:
#!/bin/sh
ACCESS_INFO=`curl -X DELETE -i -H "" -k https://:7300/api/v1/accesscontrols/ACCESS_CONTROL_ID?accountdomain=`
echo "$ACCESS_INFO"
Replace all with real values.
Warning
Delete ACL can trigger resorting of ACL IDs. Before every DELETE operation call GET operation to check what is current ACL ID. Never call two DELETE operations because ID can change after the first DELETE. operation
Locations
Get list of locations
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewLocations permission.
Does not require Advanced API permissions.
- Path:
/locations
- Method:
GET
- Parameters:
locationtype: int
location type. This parameter can be specified more than once. Recognized types: 1 = gateway IPv4 address, 2 = IPv4 subnet, 3 = IPv4 range, 4 = WiFi SSID.locationdata: string
location search data. This parameter can be specified more than once and must correspond to the location type. The subnet is specified in the format “192.168.1.100/24”, IP range is specified in the format “192.168.1.100-192.168.1.200”.
- Returns:
list
- Errors: 400
#!/bin/sh
ACCESS_INFO=`curl -X GET -i -H "X-Api-Key:" -k "https://:7300/api/v1/locations?locationtype=1&locationdata=192.168.1.100"`
echo "$ACCESS_INFO"
Replace all with real values.
Get location by id
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewLocations permission.
Does not require Advanced API permissions.
- Path:
/locations
- Method:
GET
- Parameters:
locationId=
The location ID
- Returns:
LocationInfo
- Errors: 404
#!/bin/sh
ACCESS_INFO=`curl -X GET -i -H "X-Api-Key:" -k "https://:7300/api/v1/locations/"`
echo "$ACCESS_INFO"
Replace all with real values.
Create location
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewLocations and CreateLocations permissions.
- Path:
/locations
- Method:
POST
- Parameters:
LocationInfo
as JSON payload, exceptid
property – skip it - Returns:
ErrorCodeInfoId
,id
property will contain a newly generated location identifier - Errors: 400, 403
curl -X POST -H "X-Api-Key: advanced_api_permissions_key" -k "https://serveraddress:7300/api/v1/locations" --data-binary @- << EOF
{
"name": "Location name",
"identifiers": [
{
"locationType": 1,
"stringData": [
"192.168.1.100"
]
}
]
}
EOF
Update existing location by id
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewLocations and ModifyLocations permissions.
- Path:
/locations/*id*
- Method:
PUT
- Parameters:
LocationInfo
as JSON payload - Returns:
LocationInfo
- Errors: 400, 403, 404
curl -X PUT -H "X-Api-Key: advanced_api_permissions_key" -k "https://serveraddress:7300/api/v1/locations/LOCATION_ID" --data-binary @- << EOF
{
"name": "Location name",
"identifiers": [
{
"locationType": 1,
"stringData": [
"192.168.1.100"
]
}
]
}
EOF
Replace LOCATION_ID
with real value.
Delete location by id
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewLocations and DeleteLocations permissions.
- Path:
/locations/*id*
- Method:
DELETE
- Parameters: None
- Returns:
ErrorCodeInfoId
- Errors: 403, 404
curl -X DELETE -H "X-Api-Key: advanced_api_permissions_key" -k "https://serveraddress:7300/api/v1/locations/LOCATION_ID"
Replace LOCATION_ID
with real value.
Card reader
Release all jobs using the card reader
Permission info
Does not require Advanced API permissions.
Path: /card
- Method:
GET
,POST
- Parameters:
cd: string
required user card reader IDMac: string
required printer IP card reader address
- Returns: 200 Success
- Errors: 400
- Notes: For
POST
method, the parameters must be sent as query parameters, not body parameters.
cURL example:
curl -X GET -i -v -H "X-Api-Key: " -k "https://:7300/api/v1/card/?cd=&amp;Mac="
Groups
Get list of local groups
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewUser permission.
- Path:
/groups
- Method:
GET
- Parameters:
- Returns:
list
cURL example:
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/groups"
Create local user group
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewUser and CreateUser permissions.
- Path:
/groups
- Method:
PUT
- Parameters:
groupname: string
required local group namegroupdn
optional group ID. If omitted, a unique group ID will be generated.
- Returns:
ErrorCodeInfo
which contains a new group ID - Errors: 400
cURL example:
curl -X PUT -i -H "X-Api-Key: " -k "https://:7300/api/v1/groups" -d groupname= -d groupdn=
Delete local user group
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewUser and DeleteUser permissions.
- Path:
/groups/
- Method:
DELETE
- Parameters:
GROUPID: pathparam
path parameter which indicates either group primary key (integer) or group ID (string)
- Returns:
ErrorCodeInfo
cURL example:
curl -X DELETE -i -v -H "X-Api-Key: " -k "https://:7300/api/v1/groups/"
Get info about group
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewUser permission.
- Path: /groups/
GROUPID
- Method:
GET
- Parameters:
GROUPID: pathparam
path parameter which indicates either group primary key (integer) or group ID (string)
- Returns:
GroupInfo
- Errors: 404
cURL example:
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/groups/GROUPID"
Get members of a group
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewUser permissions.
- Path: /groups/
GROUPID
/members - Method:
GET
- Parameters:
GROUPID: pathparam
path parameter which indicates either group primary key (integer) or group ID (string)
- Returns:
List<UserInfo>
- Errors: 404
cURL example:
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/groups/GROUPID/members"
Terminal config
Create terminal configuration
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewTerminalConfig and CreateTerminalConfig permissions.
- Path:
/terminalconfig
- Method:
POST
- Parameters:
domain: string
required account domain where to add the configurationname: string
required configuration namevendor: string
required printer vendor (ex: km, hp, xerox ….)adminuser: string
optional admin username. If omitted, empty is the defaultadminpassword: string
optional admin password. If omitted, empty is the defaultapplicationtype: int
optional application type (ex: 0:Other, 1:Open_API, 2: IWS, 3: Workpath). If omitted, OTHER is the defaultdevices: int
optional list of mapped output port IDs. Can be repeated multiple times
- Returns:
ErrorCodeInfo
which contains the new terminal config ID - Errors: 400
cURL example:
curl -X POST -i -H "X-Api-Key: " -k "https://:7300/api/v1/terminalconfig" -d domain= -d name= -d vendor= -d adminuser= -d adminpassword= -d applicationtype= -d devices=
Get terminal configuration
Permission info
Does not require Advanced API permissions.
Authorization with a device token or allowing untrusted endpoints is required .
This feature is only available for the Ricoh Standard Embedded Terminal.
- Path:
/terminalconfig
- Method:
GET
- Parameters:
serialnumber: string
required serial number (device serial) of the printer
- Returns:
TerminalConfig
- Errors: 400, 403, 404
cURL example:
curl -X GET -i -H "X-Api-Key: " "https://:7300/api/v1/terminalconfig?serialnumber="
curl -X GET -i -H "X-Api-Key: " -H "Authorization: " "https://:7300/api/v1/terminalconfig?serialnumber="
Token
Permission info
Does not require Advanced API permissions.
Refresh user token
- Path:
/token
- Method:
GET
- Parameters:
refresh_token: string
a refresh token acquired in the login call
- Returns:
TokenInfo
- Errors: 400, 403
cURL example:
curl -i -H "X-Api-Key: xxx" -k "https://serveraddress:7300/api/v1/token?refresh_token=yyy"
Scan Connectors
Note
This feature is currently hidden by default and may not be available for your account.
Get scan connector
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow permission.
Path:
/scan/connectors/<scanConnectorId>
Method:
GET
Parameters:
scanConnectorId: int
Id of the connector
Returns:
ScanConnectorInfo
Errors: 403, 404
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/connectors/<scanConnectorId>"
Get all scan connectors
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow permission.
Path:
/scan/connectors
Method:
GET
Returns:
list<ScanConnectorInfo>
Errors: 403, 404
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/connectors"
Update scan connector
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and ModifyScanWorkflow permissions.
Path:
/scan/connectors/<scanConnectorId>
Method:
PUT
Parameters:
scanConnectorId: int
Id of the connectorscanConnector: ScanConnectorInfo
- see Data structures.
Returns:
ScanConnectorInfo
Errors: 403, 404
curl -X PUT -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/connectors/<scanConnectorId>" --data "{\"name\":\"Connector\", \"connectorType\":\"EMAIL\"}"
Create scan connector
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and CreateScanWorkflow permissions.
Path:
/scan/connectors
Method:
POST
Parameters:
scanConnector: ScanConnectorInfo
- see Data structures.
Returns:
ScanConnectorInfo
Errors: 403, 404
curl -X POST -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/connectors" --data "{\"name\":\"Connector\", \"connectorType\":\"EMAIL\"}"
Delete scan connector
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and DeleteScanWorkflow permissions.
Path:
/scan/connectors/<scanConnectorId>
Method:
DELETE
Parameters:
scanConnectorId: int
Id of the connector
Returns: 204
Errors: 403, 404
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/connectors/<scanConnectorId>"
Scan Workflows
Note
This feature is currently hidden by default and may not be available for your account.
Get scan workflow
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow permission.
Path:
/scan/workflows/<scanWorkflowId>
Method:
GET
Parameters:
scanWorkflowId: int
Id of the workflow
Returns:
ScanWorkflowTemplateInfo
Errors: 403, 404
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/workflows/<scanWorkflowId>"
Get all scan workflows
Permission info
If you provide a user token, make sure the user for whom the token was issued has ViewScanWorkflow permission.
Path:
/scan/workflows
Method:
GET
Returns:
list<ScanWorkflowTemplateInfo>
Errors: 403, 404
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/workflows"
Update scan workflow
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and ModifyScanWorkflow permissions.
Path:
/scan/workflows/<scanWorkflowId>
Method:
PUT
Parameters:
scanWorkflowId: int
Id of the workflowscanWorkflow: ScanWorkflowTemplateInfo
- see Data structures.
Returns:
ScanWorkflowTemplateInfo
Errors: 403, 404
curl -X PUT -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/workflows/<scanWorkflowId>" --data "{\"name\":\"Workflow\", \"connectorId\":<scanConnectorId>}"
Create scan workflows
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and CreateScanWorkflow permissions.
Path:
/scan/workflows
Method:
POST
Parameters:
scanWorkflow: ScanWorkflowTemplateInfo
- see Data structures.
Returns:
ScanWorkflowTemplateInfo
Errors: 403, 404
curl -X POST -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/workflows" --data "{\"name\":\"Workflow\", \"connectorId\":<scanConnectorId>}"
Delete scan workflow
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflow and DeleteScanWorkflow permissions.
Path:
/scan/workflows/<scanWorkflowId>
Method:
DELETE
Parameters:
scanWorkflowId: int
Id of the workflow
Returns: 204
Errors: 403, 404
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/workflows/<scanWorkflowId>"
Scan Workflow Access
Note
This feature is currently hidden by default and may not be available for your account.
Get scan workflow access
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflowAccessRule permission.
Path:
/scan/access/<accessId>
Method:
GET
Parameters:
accessId: int
Id of the workflow access
Returns:
ScanWorkflowAccessInfo
Errors: 403, 404
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/access/<accessId>"
Get all scan workflow accesses
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflowAccessRule permission.
Path:
/scan/access
Method:
GET
Returns:
list<ScanWorkflowAccessInfo>
Errors: 403, 404
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/access"
Update scan workflow access
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflowAccessRule and ModifyScanWorkflowAccessRule permissions.
Path:
/scan/access/<accessId>
Method:
PUT
Parameters:
accessId: int
Id of the workflow accessaccessInfo: ScanWorkflowAccessInfo
- see Data structures.
Returns:
ScanWorkflowAccessInfo
Errors: 403, 404
curl -X PUT -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/access/<accessId>" --data "{\"workflowId\":\"100\", \"identityId\":2, \"identityType\":\"Group\"}"
Create scan workflow access
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflowAccessRule and CreateScanWorkflowAccessRule permissions.
Path:
/scan/access
Method:
POST
Parameters:
accessInfo: ScanWorkflowAccessInfo
- see Data structures.
Returns:
ScanWorkflowTemplateInfo
Errors: 403, 404
curl -X POST -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/access" --data "{\"workflowId\":\"1\", \"identityId\":2, \"identityType\":\"User\"}"
Delete scan workflow access
Permission info
If you provide a user token, make sure the user for whom the token was issued has the ViewScanWorkflowAccessRule and DeleteScanWorkflowAccessRule permissions.
Path:
/scan/access/<accessId>
Method:
DELETE
Parameters:
accessId: int
Id of the workflow access
Returns: 204
Errors: 403, 404
curl -X GET -i -H "X-Api-Key: " -k "https://:7300/api/v1/scan/access/<accessId>"
Certificates
Import a CA certificate
A ModifyCertificate permission is needed for this operation
- Path:
/certificate/ca
- Method:
POST
- Body: "application/octet-stream" of PEM/DER file
- Returns: 200 and CertificateInfo structure which contains
alias
serial
subject
issuer
notBefore
notAfter
body
(public part of the certificate)
- Errors: 400
curl -X POST -k -i -H X-Api-Key:$API_KEY -H Content-Type:application/octet-stream --data-binary "@cacert.pem" https://:7300/api/v1/certificate/ca
Import private certificate chain
A ModifyCertificate permission is needed for this operation
- Path:
/certificate/chain
- Method:
POST
- Body: "multipart/form-data" with two parts:
- "
password
" part, which contains a keystore password (string) - "
data
" part, which contains binary stream of P12/PFX file
- "
- Returns: 200 and list of
CertificateInfo
structure which containsalias
serial
subject
issuer
notBefore
notAfter
body
(public part of the certificate)
- Errors: 400
curl -X POST -k -i -H X-Api-Key:$API_KEY -F data="@chain.p12" -F password=changeit https://:7300/api/v1/certificate/chain
Get a CA certificate
A ViewCertificate permission is needed for this operation
- Path:
/certificate/ca
- Method:
GET
- Optional query parameters (you can combine them):
subject
(could be a substring)serial
(bigint)alias
(string)issuer
(string)expiresin
(int - number of days)
- Returns: 200 and list of
CertificateInfo
structure which containsalias
serial
subject
issuer
notBefore
notAfter
body
(public part of the certificate)
- Errors: 400
curl -k -i -H X-Api-Key:$API_KEY https://:7300/api/v1/certificate/ca?serial=828286999265050717
Get private certificate chain
A ViewCertificate permission is needed for this operation
- Path:
/certificate/chain
- Method:
GET
- Optional query parameters (you can combine them):
subject
(could be a substring)serial
(bigint)alias
(string)issuer
(string)expiresin
(int - number of days)
- Returns: 200 and list of
CertificateInfo
structure which containsalias
serial
subject
issuer
notBefore
notAfter
body
(public part of the certificate)
- Errors: 400
curl -k -i -H X-Api-Key:$API_KEY https://:7300/api/v1/certificate/chain?subject=CA
Delete a CA certificate
A DeleteCertificate permission is needed for this operation
- Path:
/certificate/ca/<alias>
- Method:
DELETE
- Mandatory path parameter:
alias
- Returns: 200
- Error codes: 1130, 1134
curl -X DELETE -k -i -H X-Api-Key:$API_KEY https://:7300/api/v1/certificate/ca/imported-aeba53f2-78cf-4fad-b134-d61c5e940cdc
Delete private certificate chain
A DeleteCertificate permission is needed for this operation
- Path:
/certificate/chain/<alias>
- Method:
DELETE
- Mandatory path parameter:
alias
- Returns: 200
- Error codes: 1131, 1135
curl -X DELETE -k -i -H X-Api-Key:$API_KEY https://:7300/api/v1/certificate/chain/7c9c05e5-2622-4c9d-9f76-2c11a6d24846