Usage
The JFrog Platform REST API endpoints can be invoked in any of the standardways to invoke a RESTful API. This section describes how to use the Platform REST API using cURL as an example.
Using and Configuring cURL
Authentication
JFrog Platform's REST API supports these forms of authentication:
- Basic authentication using your username and password
- Using anaccess tokeninstead of a password for basic authentication.
- Using anaccess tokenas a bearer token in an authorization header(
授权:arer) with your access token.
Base URL
The REST URL is constructed of:
 Code Block |
|---|
http:// |
For example:
|
Code Block |
|---|
http://localhost:8082/access/api/v1/ |
Working with the JFrog Platform on the Cloud
The JFrog Platform on the Cloud offers the same extensive functionality and capabilities for automation as a self-hosted installation, including authentication, use of JFrog CLI, and the REST API endpoints.
As a Cloud service, the URL is different from a self-hosted installation and the REST API endpoints can be reached at:
https://.jfrog.io/artifactory/
Example
The snippets below apply the sameexampledescribed above to an Artifactory Cloud instance named "myArtifactoryCloud" (instead of to a self-hosted installation).
To deploy the file using yourusername and passwordfor authentication, you would use the following command:
curl -u myUser:myP455w0rd! -X PUT "https://myartifactorycloud.jfrog.io/artifactory/my-repository/my/new/artifact/directory/file.txt" -T Desktop/myNewFile.txt
jfrog rt u file.txt my-repository/my/new/artifact/directory/ --user=myUser --password=myP455w0rd!
Note that using JFrog CLI is identical with an Artifactory Cloud instance. You only need toconfigure JFrog CLIwith the correct URL for your instance.
REST Resources
The sections below provide a comprehensive listing of the REST resources exposed by JFrog Platform.
For details on handling errors, seeERROR RESPONSESin the JFrog Artifactory REST APIs.
Usage of REST resources is subject to security restrictions applicable to each individual resource.
SECURITY
The Security APIs, available from Artifactory release 7.49.3, replace the previousSecurity APIs, which are planned to be deprecated at a later stage.The new APIs address all aspects of JFrog Platform security and access.
JFrog is currently exposing the new Security REST APIs that are already available; these APIs are being modified and in the coming periods will be added to and will replace the previous APIs, but will remain backward-compatible.
Users
The Security API for users include the following APIs.
Query Strings
The User APIs use the following recurring query strings:
| String | Description |
|---|---|
| Realm | An enum string with the possible values: internal, saml, oauth, ldap, crowd, scim, etc. |
| Status | An enum string with the possible values: invited, enabled, disabled, locked |
| uri | A uri string to theGet Usernameendpoint |
Get Username
Description:Returns the user's details based on the username.
Since: 7.49.3
Authorization:Requires admin permissions
Usage: GET/access/api/v2/users/{username}
Produces: application/json
Sample Response:
{ "username": "string", "email": "string", "groups": [ "string" ], "realm": "string", "status": "enabled", "admin": true, "profile_updatable": true, "internal_password_disabled": true, "disable_ui_access": true }
Response Codes:
- 200: Successful
- 400: Invalid input, object invalid
- 401: Invalid credentials
- 403: Insufficient permissions
- 404:Username not found
Get User List
Description:Returns the list of users.
Since: 7.49.3
Authorization:Requires admin permissions
Usage: GET /access/api/v2/users
Produces: application/json; charset=UTF-8
Response:
{ "users": [ { "username": "string", "realm": "string", "status": "enabled", "uri": "string" } ] }
The limit limits theresult set; the valid values are between 1 to 99999 (the default is 1000).
Response Codes:
- 200: Successful
- 400: Invalid input, object invalid
- 401: Invalid credentials
- 403: Insufficient permissions
Create User
Description:Creates a new Access user.
Since: 7.49.3
Authorization:Requires admin permissions
Usage: POST /access/api/v2/users
Content-Type:application/json
Produces: application/json
Request:
{ "username": "logenn", "password": "string", "email": "string", "groups": [ "string" ], "admin": false, "profile_updatable": true, "internal_password_disabled": false, "disable_ui_access": false }
When ‘internal_password_disabled=true`, the ‘password” field is not mandatory.
The parameterrealmwill be internal.
Response:
{ "username": "string", "email": "string", "groups": [ "string" ], "realm": "string", "status": "enabled", "admin": true, "profile_updatable": true, "internal_password_disabled": true, "disable_ui_access": true }
Response Codes:
- 201: Successful
- 400: Invalid input, object invalid
- 401: Invalid credentials
- 403: Insufficient permissions
- 409: User already exists
Update a User (Partial Update)
Description:Updates an existing Access user.
Since: 7.49.3
Authorization:Requires admin permissions
Usage: PATCH/access/api/v1/users/{username}
Produces: application/json
Request:
{ "email": "string", "password": "string", "admin": true, "profile_updatable": true, "internal_password_disabled": true, "disable_ui_access": true }
- All fields are optional; if a specific field is not specified the value will not change.
- When ‘
internal_password_disabled=false` and this field was true before, the ‘password” field is mandatory.
Response:
{ "username": "string", "email": "string", "groups": [ "string" ], "realm": "string", "status": "enabled", "admin": true, "profile_updatable": true, "internal_password_disabled": true, "disable_ui_access": true }
Delete User
Description:Delete an existing user based on the username.
Since: 7.49.3
Authorization:Requires admin permissions
Usage: DELETE/access/api/v2/users/{username}
Response Codes:
- 204: Successful
- 400: Invalid input, object invalid
- 401: Invalid credentials
- 403: Insufficient permissions
- 404: Username not found
Add or Remove User from Groups
Description:Add or remove groups from a user.
Since: 7.49.3
Authorization:Requires admin permissions
Usage:PATCH/access/api/v2/{username}/groups
Content-Type:application/json
Produces: application/json
Request:
{ "add": [ "string" ], "remove": [ "string" ] }
Response:
{ "groups": [ "string" ] }
Response Codes:
Returns a 400 code in the following cases:
- If both add and remove are not provided
- If the same value appears in both add and remove lists
- If one of the lists contains a non-existent group
Change a User Password
Description:Change a user password.
Since: 7.49.3
Authorization:Requires admin permissions or user is the same as {username}
Usage: PUT/access/api/v2/{username}/password
Content-Type: application/json
Request:
{ "password": "string" }
ResponseCodes:
- 204: Successful
- 400: Failed - Any failed update should result in 400 with a message; also ‘
if user set with internal_password_disabled=true`
Set User Password as Expired
Description:Set a user password as expired.
Since: 7.49.3
Authorization:Requires admin permissions
Usage:POST/access/api/v2/{username}/password/expire
Request: Blank
Response Code:204(Successful)
Unlock User
Description:Unlocks a locked user.
Since: 7.49.3
Authorization:Requires admin permissions
Usage:POST/access/api/v2/{username}/unlock
Request: Blank
Response Code:204(Successful)
Groups
Query Strings
The Group APIs use the following recurring query strings:
| String | Description |
|---|---|
| Realm | An enum string with the possible values: internal, saml, oauth, ldap, crowd, scim, etc. |
| Status | An enum string with the possible values: invited, enabled, disabled, locked |
| uri | A uri string to theGet Group Detailsendpoint. |
Get Group Details
Description:Returns the groups' detailsbased on the group name.
Since: 7.49.3
Authorization:Requires admin permissions
Usage: GET/access/api/v2/groups/ {name}
Produces: application/json
Response:
{" name": "string", "description": "string", "autoJoin": false, "adminPrivileges": false, "realm": "ldap", "realmAttributes": "string", "externalId": "string", "members": "[\"user1\", \"user2\"]" }
Response Codes:
- 200: Successful
- 400: Invalid input, object invalid
- 401: Invalid credentials
- 403: Insufficient permissions
- 404: Group not found
Get a List of Groups
Description:Returns the list of all groups.
Since: 7.49.3
Authorization:Requires admin permissions
Usage: GET /access/api/v2/groups
Produces: application/json
Response:
{ "cursor": "string", "groups": [ { "group_name": "string", "uri": "string" } ] }
The limit limits theresult set; the valid values are between 1 to 99999 (the default is 1000).
Response Codes:
- 200: Successful
- 400: Invalid input, object invalid
- 401: Invalid credentials
- 403: Insufficient permissions
Create a Group
Description:Creates a new group.
Since: 7.49.3
Authorization:Requires admin permissions
Usage: POST/access/api/v2/groups
Produces: application/json
Response:
{" name": "string", "description": "string", "autoJoin": false, "adminPrivileges": false, "realm": "ldap", "realmAttributes": "string", "externalId": "string", "members": "[\"user1\", \"user2\"]" }
Response Codes:
- 200: Successful
- 400: Invalid input, object invalid
- 401: Invalid credentials
- 403: Insufficient permissions
- 409: Group already exists
Group Update
Description: Updates an Access group.
Since: 7.49.3
Authorization:Requires admin permissions
Usage: PATCH/access/api/v2/groups/ {name}
Produces: application/json
All fields are optional; if a field is not specified the value will not change (if the request payload is empty, returns 200)
{" name": "string", "description": "string", "autoJoin": false, "adminPrivileges": false, "realm": "ldap", "realmAttributes": "string", "externalId": "string", "members": "[\"user1\", \"user2\"]" }
Response Codes:
- 200: Successful
- 400: Invalid input, object invalid
- 401: Invalid credentials
- 403: Insufficient permissions
- 404: Name not found
Delete a Group
Description:Deletes an existing group based on the group name.
Since: 7.49.3
Authorization:Requires admin permissions
Usage: DELETE/access/api/v2/groups/{name}
Request: Blank
Response Codes:
- 204: Successful
- 400: Invalid input, object invalid
- 401: Invalid credentials
- 403: Insufficient permissions
- 404: Group not found
Add or Remove a Group Member
Description:Manage group members by adding and removing group members.
Since: 7.49.3
Authorization:Requires admin permissions
Usage: PATCH/access/api/v2/groups/{name}/members
Content-Type:application/json
Produces: application/json
Request:
{ "add": "[\"user1\", \"user2\"]", "remove": "[\"user1\", \"user2\"]" }
Response:
{ "members": "[\"user1\", \"user2\"]" }
Response Codes:
Returns a 400 code in the following cases:
- If both add list and remove list are not provided
- If the same value appears in both add list and remove list
- If one of the lists contains a non-existent group
SYSTEM & CONFIGURATION
System Info
Description: System Info
Get general system information.
Since: 2.2.0
Security: Requires a valid admin user
Usage: GET /api/system
Produces: text/plain
Sample Output:
GET /api/system system info output text
System Health Ping
Description: Get a simple status response about the state of Artifactory.
Since: 2.3.0
Security: Requires a valid user (can be anonymous).
Usage: GET /api/system/ping
Produces: text/plain
Sample Output:
GET /api/system/ping OK
Response status codes:
200 - Successful request with an 'OK' text if Artifactory is working properly, if not will return an HTTP error code with a reason.
Readiness Probe
Description: The readiness probe, which essentially replaces the system/ping (above), returns a simple status response about the state of Artifactory using the new Kubernetes style readiness probe (the system/ping will remain in place for legacy systems still depending on it). The probe can be used to measure the system latency, provides customers with an important metric to monitor according to their standard.
Since: 7.31.x
Security: Requires a valid user (can be anonymous).
Usage: GET /api/v1/system/readiness
Produces: application/json
Sample Output:
GET /api/v1/system/readiness OK
Response status codes:
200 - Successful request with an 'OK' text if Artifactory is working properly, if not will return an HTTP error code with a reason
Liveness Probe
Description: Get a status response to know when a container is ready to start accepting traffic.
Since: 7.31.x
Security: Requires a valid user (can be anonymous).
Usage: GET /api/v1/system/liveness
Produces: application/json
Sample Output:
GET /api/v1/system/liveness OK
Response status codes:
200 - Successful request with an 'OK' text if working properly; if not will return an HTTP error code with a reason
Verify Connection
Description: Verifies a two-way connection between Artifactory and another product
Returns Success (200) if Artifactory receives a similar success code (200) from the provided endpoint. See possible error codes below.
Since: 4.15.0
Security: Requires an admin user.
Usage: POST/api/system/verifyconnection
Consumes:application/json
POST /api/system/verifyconnection { + "endpoint" : "", - "username" : "", - "password" : "" }
Produces: application/json
Upon success (200): 200 Successfully connected to endpoint Upon error, returns 400 along with a JSON object that contains the error returned from the other system.
Sample Output:
{ "errors" : [ { "status" : 400, "message" : "Received error from endpoint url: HTTP 404: Page not found" } ] }
General Configuration
This API is available only in Self-hosted instances.
Description: Get the general configuration (artifactory.config.xml).
Since: 2.2.0
Security: Requires a valid admin user
Usage: GET /api/system/configuration
Produces: application/xml (http://www.jfrog.org/xsd/artifactory-v1_7_3.xsd)
To download the xsd file above, you will need to copy and pastehttp://www.jfrog.org/xsd/artifactory-v1_7_3.xsdto a new tab in your brower.
To
Sample Output:
GET /api/system/configuration
Save General Configuration
Description: Save the general configuration (artifactory.config.xml).
This API is available only in Self-hosted instances.
Since: 2.2.0
Notes: This is an advanced feature - make sure the new configuration is really what you wanted before saving.
Security: Requires a valid admin user
Usage: POST /api/system/configuration
Consumes: application/xml (http://www.jfrog.org/xsd/artifactory-v1_7_3.xsd)
To download the xsd file above, you will need to copy and pastehttp://www.jfrog.org/xsd/artifactory-v1_7_3.xsdto a new tab in your brower.
Sample Usage:
POST /api/system/configuration
Update Custom URL Base
Description:Changes the Custom URL base
Since: 3.9.0
Security: Requires a valid admin user
Usage: PUT /api/system/configuration/baseUrl
Example:curl -X PUT "http://localhost:8081/artifactory/api/system/configuration/baseUrl" -d 'https://mycompany.com:444' -uadmin:password -H "Content-type: text/plain"
Sample Output:
URL base has been successfully updated to "https://mycompany.com:444".
License Information
Description: Return information about the currently installed license.
Since: 3.3.0
Security: Requires a valid admin user
Usage: GET /api/system/license
Produces:application/json
Sample Output:
GET /api/system/license { "type" : "Commercial", "validThrough" : "May 15, 2014", "licensedTo" : "JFrog inc." }
Install License
Description: Install new license key or change the current one.
Since: 3.3.0
Security: Requires a valid admin user
Usage: POST /api/system/licenses
Consumes:application/json
POST /api/system/licenses { "licenseKey": "" // Any newline characters must be represented by escape sequence (\n) }
Produces:application/json
Sample Output:
POST /api/system/licenses { "status" : 200, "message" : "The license has been successfully installed." }
HA License Information
Description: Return information about the currently installed licenses in an HA cluster.
Since: 5.0.0
Security: Requires a valid admin user
Usage: GET /api/system/licenses
Produces:application/json
[ { "type" : "Enterprise", "validThrough" : "", "licensedTo" : "", "licenseHash" : "", "nodeId" : "", "nodeUrl" : "", "expired" : }]
Sample Output:
GET /api/system/licenses [ { "type" : "Enterprise", "validThrough" : "May 15, 2018", "licensedTo" : "JFrog", "licenseHash" : "179b7ea384d0c4655a00dfac7285a21d986a17923", "nodeId" : "art1", "nodeUrl" : "http://10.1.16.83:8091/artifactory", "expired" : false }, { "type" : "Enterprise", "validThrough" : "May 15, 2018", "licensedTo" : "JFrog", "licenseHash" : "e10b8aa1d1dc5107439ce43debc6e65dfeb71afd3", "nodeId" : "Not in use", "nodeUrl" : "Not in use", "expired" : false } ]
Install HA Cluster Licenses
Description: Install a new license key(s) on an HA cluster.
Since: 5.0.0
Security: Requires an admin user
Usage: POST /api/system/licenses
Consumes:application/json
POST /api/system/licenses [{ "licenseKey": "" // Any newline characters must be represented by escape sequence (\n) }]
Produces:application/json
{ "status" : 200, "messages" : { ["" : ""] }
Sample Usage:
POST /api/system/licenses [ { "licenseKey": "tL9r2Y...lDBiktbbt" }, { "licenseKey": DiYgVA...P7nvyNI7q" } ] Response: { "status" : 200, "messages" : { "tL9r2Y...lDBiktbbt" : "OK", "DiYgVA...P7nvyNI7q" : "OK", }
Delete HA Cluster License
Description: Deletes a license key from an HA cluster.
Since: 5.0.0
Security: Requires an admin user
Usage: DELETE /api/system/licenses?licenseHash=licenseHash1, licenseHash2...
Produces:application/json
{ "status" : 200, "messages" : {["" : ""]} }
Sample Usage:
DELETE /api/system/licenses?licenseHash=tL9r2YlDBiktbbt, DiYgVAP7nvyNI7q Response: { "status" : 200, "messages" : { "tL9r2YlDBiktbbt" : "OK", "DiYgVAP7nvyNI7q" : "OK" } }
Version and Add-ons information
Description: Return information about the current Artifactory version, revision, and currently installed Add-ons
Since: 2.2.2
Security: Requires a valid user (can be anonymous)
Usage: GET /api/system/version
Produces:application/json (application/vnd.org.jfrog.artifactory.system.Version+json)
Sample Output:
GET /api/system/version { "version" : "2.2.2", "revision" : "10427", "addons" : [ "build", "ldap", "properties", "rest", "search", "sso", "watch", "webstart" ] }
Get Reverse Proxy Configuration
Description: Returns the reverse proxy configuration.
This API is available only in Self-hosted instances.
Since: 4.3.1
Note:Applicable to a Self-Hosted JFrog Platform only
Security: Requires a valid admin userand supported for users with the relevant permissions.
Non-admin users will get the proxy method and ports and the list of repositories based on their user permissions.
Usage:GET /api/system/configuration/webServer
Produces: application/json
Sample Output:
GET / api /系统/配置/网络服务器{“关键”:"nginx", "webServerType" : "NGINX", "artifactoryAppContext" : "artifactory", "publicAppContext" : "artifactory", "serverName" : "m.si-fil.com", "serverNameExpression" : "*.m.si-fil.com", "artifactoryServerName" : "localhost", "artifactoryPort" : 8081, "sslCertificate" : "/etc/ssl/myKey.cert", "sslKey" : "/etc/ssl/myKey.key", "dockerReverseProxyMethod" : "SUBDOMAIN", "useHttps" : true, "useHttp" : true, "sslPort" : 443, "httpPort" : 76 }
Possible Values for dockerReverseProxyMethod
The table below maps the possible values for thedockerReverseProxyMethodfrom the JFrog Platform UI to the Reverse Proxy API:
| UI Value | API Value |
|---|---|
| Subdomain | SUBDOMAIN |
| Repository Path | REPOPATHPREFIX |
| Port | PORTPERREPO |
Update Reverse Proxy Configuration
Description: Updates the reverse proxy configuration.
This API is available only in Self-hosted instances.
Since: 4.3.1
Security: Requires an admin user
Usage: POST/api/system/configuration/webServer
Consumes:application/json
Sample Usage:
POST /api/system/configuration/webServer { "key" : "nginx", "webServerType" : "NGINX", "artifactoryAppContext" : "artifactory", "publicAppContext" : "artifactory", "serverName" : "m.si-fil.com", "serverNameExpression" : "*.m.si-fil.com", "artifactoryServerName" : "localhost", "artifactoryPort" : 8081, "sslCertificate" : "/etc/ssl/myKey.cert", "sslKey" : "/etc/ssl/myKey.key", "dockerReverseProxyMethod" : "SUBDOMAIN", "useHttps" : true, "useHttp" : true, "sslPort" : 443, "httpPort" : 76 }
Get Reverse Proxy Snippet
Description: Returns the reverse proxy configuration snippet in text format
Since: 4.3.1
Security: Requires a valid user (not anonymous)
Usage: GET/api/system/configuration/reverseProxy/nginx
Produces:text/plain
Sample Usage:
GET /api/system/configuration/reverseProxy/nginx ## add ssl entries when https has been set in config ssl_certificate /etc/ssl/myKey.cert; ssl_certificate_key /etc/ssl/myKey.key; ssl_session_cache shared:SSL:1m; ssl_prefer_server_ciphers on; ## server configuration server { listen 443 ssl; listen 76 ; server_name ~(?.+)\.m.si-fil.com m.si-fil.com; if ($http_x_forwarded_proto = '') { set $http_x_forwarded_proto $scheme; } ## Application specific logs ## access_log /var/log/nginx/m.si-fil.com-access.log timing; ## error_log /var/log/nginx/m.si-fil.com-error.log; rewrite ^/$ /artifactory/webapp/ redirect; rewrite ^/artifactory$ /artifactory/webapp/ redirect; }
Start SHA256 Migration Task
Description: Starts theSHA-256migration process.
Note: Migration can also be configured using aset of properties in Artifactory's artifactory.system.properties file.
Security: Administrator permissions
Usage: POST api/system/migration/sha2/start
Since: 6.6.0
Consumes:application/json
{ - "batchThreshold":10 (default), - "queryLimit":100 (default), - "waitForClusterSleepIntervalMillis":5000 (default), - "sleepIntervalMillis":5000 (default), - "forceRunOnNodeId":"" }
Produces:text/plain
Sample Output:
Sha256 migration scheduled to start successfully
Stop SHA256 Migration Task
Description: Stops theSHA-256migration process
Security: Administrator permissions
Note: ThesleepIntervalMillisshould match what was defined in theStart SHA256 Migration Task
Usage: POST api/system/migration/sha2/stop?{sleepIntervalMillis=5000}
Produces:text/plain
Since: 6.6.0
Sample Output:
Sha256 migration scheduled to stop successfully.
Create Bootstrap Bundle (Deprecated)
Description: This rest is relevant for High Availability set up. It will create a bootstrap bundle on the primary node of an Artifactory HA installation that will include all the relevant keys so a new node can access the database and fetch all the relevant configuration files. The same bundle must be installed on all nodes during an installation of new nodes or if upgrading from a version older than 5.0.
Note:Deprecated from version 5.7
Since: 5.0.0
Until: 5.6.x
Security:Requires an admin user
Usage: POST /api/system/bootstrap_bundle
Produces: application/json
{ "file" : "" }
Sample usage:
POST /api/system/bootstrap_bundle { "file" : "/opt/jfrog/artifactory/etc/bootstrap.bundle.tar.gz" }
Re-index paths on Metadata Server
Description:If needed, Artifactory can re-send Metadata events to the Metadata Server in case of an inconsistent state. The API will recursively re-index artifacts under the given repository or path if a repository key or a directory path is specified.Asynchronousby default. Does not delete data associated with the given paths on the Metadata Server before re-indexing by default.
Since: 7.0.0
Security:Requires an admin user
Usage: POST /api/metadata_server/reindex?[async=true/false&delete_first=true/false]
Consumes:application/json
{ "paths": ["libs-release-local", "libs-snapshot-local"] }
Produces: text/plain
Sample usage:
POST /api/metadata_server/reindex
Apply Artifactory YAML Configuration Changes
Description:Configure an existing Artifactory instance using a simple YAML configuration file. Make single or multiple configuration changes as needed, to create, update, and delete any elements in Artifactory. For more information, seeArtifactory YAML Configuration.
Take care when modifying Artifactory configurations
Modifying the Artifactory configurations is an advanced feature, and if done incorrectly may render Artifactory in an undefined and unusable state. Since it is easy to overwrite configurations, such as a repository's package type, we strongly recommend backing up the configuration before making any direct changes, and taking great care when doing so.
Since: 5.8.0
Security:Requires an admin user
Usage:PATCH /api/system/configuration -H "Content-Type: application/yaml" -T configuration.yml
Consumes:application/json
Produces: text/plain
SUPPORT
Create Bundle
Description: Create a new support bundle.
Since:4.3.0
Security:Requires an admin user
Notes: All bundle items are optional.
Usage: POST /api/system/support/bundle/
Sample Usage:
POST /api/system/support/bundle { "name":"", "description":"", "parameters":{ "configuration": "", // Default: true. "system": "", // Default: true. "logs":{ "include": "", // Default: true. "start_date":"", "end_date":"" }, "thread_dump":{ "count": , "interval": } } }
List Bundles
Description: Lists previously created bundle currently stored in the system.
Since: 4.3.0 (updated in 6.8.0)
Security: Requires a privileged user (Admin only)
Usage: GET /api/system/support/bundles/
Produces: application/json
Sample Usage:
GET /api/system/support/bundles { "bundles" : [ { "id" : "B1-1551008826805", "name" : "B1", "description" : "abc", "created" : "2019-02-24T13:47:06+02:00", "status" : "success" }, { "id" : "B2-1551008834948", "name" : "B2", "description" : null, "created" : "2019-02-24T13:47:14+02:00", "status" : "success" } ], "count" : 2 }
Get Bundle Metadata
Description: Downloads the metadata for a previously created bundle currently stored in the system.
Since: 6.8.0
Security: Requires a privileged user (Admin only)
Usage: GET /api/system/support/bundle/{bundle-id}
Produces: application/json
Sample Usage:
GET /api/system/support/bundle/B1-1551008826805 { "name" : "B1", "description" : "abc", "id" : "B1-1551008826805", "artifactory" : { "service_id" : "jfrt@01d482vam7aj0v1w9yjfpe1jnh", "bundle_url" : "http://localhost:8081/artifactory/jfrog-support-bundle/B1-1551008826805/jfrt/jfrt@01d482vam7aj0v1w9yjfpe1jnh" }, "parameters" : { "configuration" : true, "system" : true, "logs" : { "include" : true, "start_date" : "2019-02-24", "end_date" : "2019-02-24" }, "thread_dump" : { "count" : 1, "interval" : 0 } }, "created" : "2019-02-24T13:47:06+02:00", "status" : "success" }
Get Bundle
Description: Downloads a previously created bundle currently stored in the system.
Since: 4.3.0 (updated in 6.8.0)
Security: Requires a privileged user (Admin only)
Usage: GET /api/system/support/bundle/{bundle-id}/archive
Produces: application/json
Sample Usage:
GET /api/system/support/bundle/B1-1551008826805/archive
Delete Bundle
Description: Deletes a previously created bundle from the system.
Since: 4.3.0 (updated in 6.8.0)
Security: Requires a privileged user (Admin only)
Usage: DELETE /api/system/support/bundle/{bundle-id}
Produces: application/json
Sample Usage:
DELETE /api/system/support/bundle/B1-1551008826805
ACCESS
Base URL
/access/api/v1 #For example: http://ARTIFACTORY_SERVER_HOSTNAME:8082/access/api/v1
Export Access Configuration
Description: Creates a JSON file with the Access configuration as$JFROG_HOME/artifactory/var/backup/access
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage: POST /api/v1/system/backup/export
Sample Usage:
curl -H "Authorization: Bearer" -XPOST "http://localhost:8082/access/api/v1/system/backup/export"
Import Access Configuration
Description: Reads and imports an Access configuration JSON file:$JFROG_HOME/artifactory/var/etc/access/access.bootstrap.json
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage: POST /api/v1/system/backup/import
Sample Usage:
curl -H "Authorization: Bearer" -XPOST "http://localhost:8082/access/api/v1/system/backup/import"
Ping Request
Description:Sends a ping request
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage:GET /system/ping
Produces:text/plain
Sample usage:
curl -H "Authorization: Bearer" http://localhost:8082/access/api/v1/system/ping
Response Codes:200 Ping successful
Get Root Certificate
Description:Get public Root Certificate
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage:GET/api/v1/cert/root
Produces:text/plain
Query parameter (optional):?formatted=true-returns the certificate in a formatted representation (prefix, suffix and alignment)
Sample usage:
curl -H "Authorization: Bearer" http://localhost:8082/access/api/v1/cert/root or curl -H "Authorization: Bearer " http://localhost:8082/access/api/v1/cert/root?formatted=true
Response Codes:
200 successful
Access Federation
Get All Access Federations
Description:Returns all federation targets' configurations.
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage:GET/api/v1/system/federation
Produces:text/plain
Sample Usage
curl - h得到“授权:无记名<标记> http://localhost:8082/access/api/v1/system/federation/" -H "accept: application/json"
Response Codes:
200Successful operation
{ "configurations": [ { "name": "access-2", "url": "https://access.example.com/access/", "entities": [ "users", "groups", "permissions" ], "permissionFilters": { "includePatterns": [ "team_a_*" ], "excludePatterns": [ "none_federated_*" ] }, "active": true } ] }
401 / 403Unauthenticated or unauthorized
Register Access Federation
Description:Registers a new federation target.
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage:POST /api/v1/system/federation
Produces:text/plain
Sample usage:
curl -H "Authorization: Bearer" http://localhost:8082/access/api/v1/system/federation/" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"name\": \"access-2\", \"url\": \"https://access.example.com/access/\", \"entities\": [ \"users\", \"groups\", \"permissions\" ], \"permissionFilters\": { \"includePatterns\": [ \"team_a_*\" ], \"excludePatterns\": [ \"none_federated_*\" ] }, \"active\": true}"
Response Codes:
201Successfully registered
{" name": "access-2", "url": "https://access.example.com/access/", "entities": [ "users", "groups", "permissions" ], "permissionFilters": { "includePatterns": [ "team_a_*" ], "excludePatterns": [ "none_federated_*" ] }, "active": true }
400Invalid input
401Unauthorized
403Forbidden
404Already exists
Get Access Federation
Description:Returns the name of the federation target to unregister.
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage:GET/api/v1/system/federation/{server_name}
Produces:text/plain
Sample Usage
curl - h得到“授权:无记名<标记> http://localhost:8082/access/api/v1/system/federation/{server_name}" -H "accept: application/json"
Response Codes:
200Successful operation
{" name": "access-2", "url": "https://access.example.com/access/", "entities": [ "users", "groups", "permissions" ], "permissionFilters": { "includePatterns": [ "team_a_*" ], "excludePatterns": [ "none_federated_*" ] }, "active": true }
401Unauthorized
403Forbidden
404No such federation target
Delete Access Federation
Description:Unregisters a federation target.
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage:DELETE /api/v1/system/federation/{server_name}
Produces:text/plain
Sample usage:
curl -H "Authorization: Bearer" DELETE "http://localhost:8082/access/api/v1/system/federation/{server_name}" -H "accept: application/json"
Response Codes:
204Successfully unregistered
401Unauthorized
403Forbidden
404No such federation target
Update Access Federation
Description:Updates(patch) federation target configurations.
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage:PATCH /api/v1/system/federation/{server_name}
Produces:text/plain
Sample usage:
curl -H "Authorization: Bearer" PATCH {{"http://localhost:8082/access/api/v1/system/federation/ {server_name} "}} -H "accept: application/json" -H "Content-Type: application/json" -d {{"{ \"entities\": [ \"users\", \"groups\", \"permissions\" ], \"permission_filters\": { \"include_patterns\": [ \"team_a_*\" ], \"exclude_patterns\": [ \"none_federated_*\" ] } , \"active\": true}"}}
Response Codes:
204Successful operation
{" name": "access-2", "url": "https://access.example.com/access/", "entities": [ "users", "groups", "permissions" ], "permissionFilters": { "includePatterns": [ "team_a_*" ], "excludePatterns": [ "none_federated_*" ] }, "active": true }
400Invalid input
401Unauthorized
403Forbidden
Validate Access Federation
Description: Validates target for circle of trust.
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage:POST /api/v1/system/federation/validate_server
Produces:text/plain
Sample usage:
curl -H "Authorization: Bearer" POST "http://localhost:8082/access/api/v1/system/federation/validate_server" -H "accept: application/json" -H "Content-Type: application/json" -d "{ \"url\": \"https://other.access\"}"
Response Codes:
204Successfully validated
400Invalid input
401Unauthorized
403Forbidden
412Precondition Failed - Circle of trust validation failed (response from target server: XXX)
Full Broadcast Access Federation
Description:Invokes Access Federation full broadcast from a single federation source to all its federation targets.
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage:PUT /api/v1/system/federation/
Sample usage:
curl -H "Authorization: Bearer" http://localhost:8082/access/api/v1/system/federation/ /full_broadcast -XPUT
Response Codes:
204Successful operation
Description:Invokes Access Federation full broadcast from a single federation source to all its federation targets. This API targets theserver's access_id.
You can obtain the access_id from thesource'saccess.config.latest.yaml's outbound section.
Security:
- Prior to release 7.12.0: Requires an admin user (basic credentials only). Requires execution from access localhost.
- From release 7.12.0: Requires a validadmin-scoped token. The API no longer supports basic authentication.
Usage:PUT /api/v1/system/federation/
Sample usage:
curl -H "Authorization: Bearer" http://localhost:8082/access/api/v1/system/federation/ /full_broadcast -XPUT
For example:
curl -H "Authorization: Bearer" http://localhost:8082/access/api/v1/system/federation/jfac@01ep443hcx10x00djcdsp31d56/full_broadcast -XPUT
Response Codes:
204Successful operation
SCIM
The following APIs will be used for managing users and groups with the SCIM protocol.
SCIM for Users
User names are converted to lowercase automatically.
GET Specific User
Description: This API will fetch the user details, where id is the username.
Usage: GET/api/v1/scim/v2/Users/
Header parameter:授权:arer
Sample response:
{ "id": "bjensenexamplecom", "userName": "bjensenexamplecom", "active": true, "emails": [ { "primary": true, "value": "bjensen@wso2.com" } ], "groups": [ { "value": "readers" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "meta": { "resourceType": "User" } }
Sample response when user does not exist:
{ "status": 404, "detail": "notexistuser isn't found", "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ] }
FIND Users by Filter
Description: This API will fetch users' details. The results are limited by the first 20 results. You can add a filter query parameter in the form offilter=userName eq "username"
Usage:GET /api/v1/scim/v2/Users
Query parameters (optional):?filter=userName eq “username”
Produces: application/scim+json; charset=UTF-8
Header parameter:授权:arer
Sample response:
{ "totalResults": 1, "itemsPerPage": 20, "startIndex": 1, "Resources": [ { "id": "bjensenexamplecom", "userName": "bjensenexamplecom", "active": true, "emails": [ { "primary": true, "value": "bjensen@wso2.com" } ], "groups": [ { "value": "readers" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "meta": { "resourceType": "User" } } ], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }
Sample response when user does not exist:
{ "totalResults": 0, "itemsPerPage": 20, "startIndex": 1, "Resources": [], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }
CREATE Users
Description: This API will create a single user.
Usage:POST/api/v1/scim/v2/Users
Consumes: application/scim+json; charset=UTF-8
Sample request:
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "userName": "yanivm@example.com", "active": true, "emails": [ { "value": "yanivm@example.com", "primary": true } ] }
Produces: application/scim+json; charset=UTF-8
Header parameter:授权:arer
Sample response:
{ "id": "yanivm@example.com", "userName": "yanivm@example.com", "active": true, "emails": [ { "primary": true, "value": "yanivm@example.com" } ], "groups": [ { "value": "readers" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "meta": { "resourceType": "User" } }
UPDATE User
Important
Update currently supports only disabling and re-enabling users.
Description: This API allows to disable or re-enable the user status by editing the “active” attribute.
Usage:PUT/api/v1/scim/v2/Users/
Sample request:
{ "id": "jbibinka2@example.com", "userName": "jbibinka2@example.com", "active": true, "emails": [ { "primary": true, "value": "jbibinka2@example.com" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ] }
Produces: application/scim+json; charset=UTF-8
Header parameter:授权:arer
Sample response:
{ "id": "jbibinka2@example.com", "userName": "jbibinka2@example.com", "active": true, "emails": [ { "primary": true, "value": "jbibinka2@example.com" } ], "groups": [ { "value": "readers" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "meta": { "resourceType": "User" } }
DISABLE User
Important
Disable currently supports only disabling/re-enabling a single user.
Description: This API allows to disable or re-enable the user status by editing the “active” attribute.
Usage:PATCH/api/v1/scim/v2/Users/
Sample request:
{"模式":[" urn: ietf: params: scim: api:消息:2.0:PatchOp"], "Operations": [{ "op": "Replace", "path": "active", "value": false }] }
Produces: application/scim+json; charset=UTF-8
Header parameter:授权:arer
Sample response:
{ "id": "jbibinka2@example.com", "userName": "jbibinka2@example.com", "active": false, "emails": [ { "primary": true, "value": "jbibinka2@example.com" } ], "groups": [ { "value": "readers" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:User" ], "meta": { "resourceType": "User" } }
DELETE User
Description: This API will delete a single user.
Usage: DELETE/api/v1/scim/v2/Users/
Sample response:204 - No Content
SCIM for Groups
The following APIs will be used for managing groups with the SCIM protocol.
Get Group by Filter
Description:This API will fetch the group details, searched by the filter query param. When a filter is not provided, the response will containallgroups (limited to thefirst 20).
Usage: GET/api/v1/scim/v2/Groups?filter = displayName eq “groupName”
Produces: application/scim+json; charset=UTF-8
Header parameter:授权:arer
Sample response:
[ { "totalResults": 1, "itemsPerPage": 20, "startIndex": 1, "Resources": [ { "displayName": "readers", "id": "readers", "description": "A group for read-only users", "members": [], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "meta": null, "resourceType": "Group" } ], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] } ]
Sample response when group does not exist:
{ "totalResults": 0, "itemsPerPage": 20, "startIndex": 1, "Resources": [], "schemas": [ "urn:ietf:params:scim:api:messages:2.0:ListResponse" ] }
Get Group by Name
Description: This API will fetch the group details.
Usage: GET/api/v1/scim/v2/Groups/
Produces: application/scim+json; charset=UTF-8
Header parameter:授权:arer
Sample response:
{ "displayName": "examplegroup", "id": "examplegroup", "members": [ { "value": "anonymous", "display": "anonymous" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "meta": { "resourceType": "Group" } }
Sample response when group is not found:
{“状态”:404年,“细节”:“examplesgroup不是佛und", "schemas": [ "urn:ietf:params:scim:api:messages:2.0:Error" ] }
Create Group
Description: This API will create a group.
Usage: POST/api/v1/scim/v2/Groups
Consumes: application/scim+json; charset=UTF-8
Header parameter:Authorization: Bearer
Sample request:
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "exampleGroup", "id": "examplegroup", "members": [ { "display": "anonymous", "value": "anonymous" } ] }
Produces:application/scim+json; charset=UTF-8
Sample response:
{ "displayName": "exampleGroup", "id": "exampleGroup", "members": [ { "value": "anonymous", "display": "anonymous" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "meta": { "resourceType": "Group" } }
Update Group
Important
Update currently supports onlyadding/removing members from the group.
Description:This API allows to add or remove members from the group.
Usage:PUT/api/v1/scim/v2/Groups/
Header parameter:授权:arer
Consumes:application/scim+json; charset=UTF-8
Sample request:
{ "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "displayName": "newName", "id": "newName", "members": [ { "display": "newMember", "value": "newMember" }, { "value": "anonymous", "display": "anonymous" } ] }
Produces: application/scim+json; charset=UTF-8
Sample response:200- OK
{ "displayName": "exampleGroup", "id": "newName", "members": [ { "display": "newMember", "value": "newMember" }, { "value": "anonymous", "display": "anonymous" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "meta": { "resourceType": "Group" } }
Patch Group
Important
Patch currently supports only adding/removing members from the group.
Description: This API allows to add/remove members from the group.
Usage: PATCH/api/v1/scim/v2/Groups/
Header parameter:授权:arer
Consumes: application/scim+json; charset=UTF-8
Sample request:
{"模式":[" urn: ietf: params: scim: api:消息:2.0:PatchOp"], "Operations": [{ "op": "Add", "path": "members", "value": [{ "$ref": null, "value": "newMember" }] }] }
Produces: application/scim+json; charset=UTF-8
Sample response:
{ "displayName": "exampleGroup", "id": "newName", "members": [ { "display": "newMember", "value": "newMember" }, { "value": "anonymous", "display": "anonymous" } ], "schemas": [ "urn:ietf:params:scim:schemas:core:2.0:Group" ], "meta": { "resourceType": "Group" } }
Delete Group
Description: This API will delete a single group.
Usage: DELETE/api/v1/scim/v2/Groups/
Header parameter:授权:arer
Sample response:204 - No Content
Access Tokens
With the release of 7.21.1, the JFrog Platform introduced a new set of token APIs, available through the'/access'context.
The new Access Token endpoints can be used to create tokens for any of the services in your JFrog Platform and to manage user access to these services.
If left at the default setting, the token will be created with the user-identity scope, which allowsusers to identify themselves in the Platform but does not grant any specific access permissions.
Recommended Configurations
The following configurations in the ‘access.config.yml’ will apply the configuration changes required for the API.
- If expiry is forced but expires_in was not provided in the request, thedefaultexpiry shall be set.
- An admin can restrict user identity tokens refresh-ability (i.e., disallow creating as refreshable)
default-expiry
- The default expiry period in seconds, this is the token expiry when the expiry is set to null.
- When set to zero, default expiry is not forced.
- Must be non-negative.
- 必须遵守(“max-expiry”> =“default-expiry”).
- Default value: 1 year
max-expiry
- The max possible expiry of non-admin tokens.
- When the value is bigger than zero - non-expirable tokens are forbidden and the user's token expiry will be limited to themax expiry value.
- When the value is zero - the user's token can be non-expirable and the token’s expiry will not be limited with a higher boundary.
- Must be non-negative.
- 必须遵守(“max-expiry”> =“default-expiry”).
- Default value: 0
allow-refreshable
- When disabled, all the user tokens will be created as non refreshable.
- Default: true
‘access.config.yml’ Example:
token: default-expiry: 31536000 max-expiry: 0 allow-refreshable: true
Create Token
Description: Creates an access token for the JFrog Platform.
Since: 7.21.1
Security:Requires a valid token.
Usage: POST /access/api/v1/tokens
Content-Type:application/x-www-form-urlencodedorapplication/json (both are supported)
Produces: application/json
Notes on the Create Token API
- The scope is checked and validated - the authenticated principal must have the proper permissions to create a token with the requested scope.
- If the scope includes
applied-permissions/userthen the token's username must be a valid existing user that is enabled (and not locked or disabled). - Only an admin can set the username for a name that is not the same as the authenticated principal
- Only an admin can create the token with a group's scope.
- The grant type is expected to be
client_credentialsfor this API call (this is the default value if not provided). From Artifactory 7.50.3, the "force revocable" flag in the tokens has been removed as a default setting and is now a Boolean parameter called
force_revocablein the Create Token REST API.When this parameter is set to true, we will add theforce_revocableflag to the token's extension.
In addition, a new configuration has been added that sets the default for setting theforce_revocabledefault when creating a new token (the default of this configuration will be "false" to ensure that the Circle of Trust remains in place.)
Sample Usage:
curl -H "Authorization: Bearer" -XPOST "http://localhost:8082/access/api/v1/tokens" -d "scope=applied-permissions/user" 200 { "token_id": " " "access_token": " ", "refresh_token": " ", // optional "expires_in": " ", // optional "scope": "applied-permissions/groups: " "scope": "applied-permissions/user", "token_type": "access_token" }
This endpoint takes the following parameters:
grant_type |
[Optional, default: "client_credentials"] The grant type used to authenticate the request. In this case, the only value supported is "client_credentials" which is also the default value if this parameter is not specified. |
username |
[Optional, default: "subject" from authentication token] |
scope |
[Optional, default: applied-permissions/user] The scope of access that the token provides. Access to the REST API is always provided by default. Administrators can set any scope,while non-admin users can only createIdentity Tokens (user scope). The supported scopes include:
The scope to assign to the token should be provided as a space-separated list of scope tokens, limited to 500 characters. |
expires_in |
[Optional, default: 1 year] 的时间,以秒为单位,需要the token to expire. Must be non-negative. |
refreshable |
[Optional, default: false] The token is not refreshable by default. |
description |
[Optional, default: empty] Free text token description. Useful for filtering and managing tokens. |
audience |
[Optional, default:*@*] A space-separated list of the other instances or services that should accept this token identified by their服务id。 Limited to 255 characters. |
include_reference_token |
[Optional, default: false] Generate a Reference Token (alias to Access Token) in addition to the full token (available from Artifactory 7.38.10). |
Errors
- 400- Invalid input, e.g.,expires_invalue is not a number, non-positive number, etc.
- 401- Unauthenticated
- 403- The requested token details are forbidden, e.g.expires_inprovided but is higher than the limit defined by the admin, the user does not have the permissions on the scope he requested, etc.
Get Tokens
Description: Returns token information, based on the authenticated principal and optional filters.
Since: 7.21.1
Security:Requires a valid token.
Usage:GET/access/api/v1/tokens
Produces: application/json
{ "tokens": [ { "token_id": "", "subject": "", "expiry": , // optional "issued_at": , "issuer": "", "description": "", // optional "refreshable": }, ... ] }
- An admin user can get all tokens.
- Non-admin user gets only the tokens where his username matches the tokens' username.
- If the query does not find any tokens, a response of 200 (i.e., successful) will be returned but with anempty list of tokens.
- Supports query parameters to filter the response:
- description=
(supports wildcard, the wildcard must to be at the end of the text) - refreshable=
- description=
Errors:
- 401- Unauthenticated
- 403- The authenticated principal has no permissions to get tokens (not a user or not an admin token)
Sample Usage:
curl -XGET -H "Authorization: Bearer" "http://localhost:8082/access/api/v1/tokens?description=my%20token*" 200 OK { "tokens":[ { }, ... ] }
Get Token by ID
Description: Returns the token information by token ID.
Since: 7.21.1
Security: Requires a valid token.
Usage: GET /access/api/v1/tokens/my-id-is-here
From Artifactory release 7.53.0, you can also use this API not only with thetoken-idbut also withmeto indicate the currently used token.
Produces: application/json
{ "token_id": "", "subject": "", "expiry": , // optional "issued_at": , "issuer": "", "description": "", // optional "refreshable": }
An Admin user can get any token.
A non-admin user can get only the a token where the subject matches the username.
Errors:
- 401- unauthenticated
- 403- the authenticated principal has no permissions to get the token
- 404- not found
Revoke Token by ID
Description: Revoke an access token by specifying the token_id
Since: 7.21.1
Security: Requires a valid token.
Usage:DELETE /access/api/v1/tokens/my-id-is-here
From Artifactory release 7.53.0, you can also use this API not only with the token-id but also with me to indicate the currently used token.
Produces: application/json
Sample Usage:
curl -H "Authorization: Bearer" -XDELETE "http://localhost:8082/access/api/v1/tokens/7e0eec..." 200 OK
这个端点可以采取以下的标准ameters:
token_id |
The ID of the token to be revoked |
- A user can only revoke tokens on which the user is based on their username.
- An admin user can revoke any token.
- A tokencanbe used to authenticate a revoke request where the target token ID is of the token being used for authentication.
- If the token ID is not found (e.g., already revoked) - return 204.
Errors:
- 400 - If the token was created by a different Artifactory instance (and therefore cannot be revoked)
- 401- Unauthenticated
- 403- The authenticated principal has no permissions to revoke the requested token
Refresh Token
Description: Refreshes an existing access tokenwithout having to provide the old token.The Refresh Token is the same API endpoint as Create Token, with a specific grant type:refresh_token.
Since: 7.37.9
Security: Requires a valid admin-scoped token.
Usage:POST /access/api/v1/tokens
Authorization:
Content-Type:application/x-www-form-urlencoded
Produces: application/json (seeCreate Token)
- Requires authentication using credentials or an access token.
- The refresh token must be valid (i.e., must exist and not be expired)
- The authenticated user must match the user of the access token being refreshed (identified by the refresh token)
Sample Usage:
200 { "token_id": "" "access_token": "", // optional "expires_in": , // optional "grant_type": "refresh_token", "refresh_token": "" }
This endpoint takes the following parameters:
grant_type |
Should be set to |
refresh_token |
The value of refresh token of the access token that needs to be refreshed: |
For all other parameters, seeCreate Token.
Errors:
- 400:If the token was created by a different Artifactory instance (and therefore cannot be refreshed)
Pairing Token
A pairing token is an access token used for the initial pairing flow. This type of token is designed as a limited access token, is dedicated to a specific task, and is short lived.
- A pairing token is created per use case, and the audience of the token targets a specific service, namely the same service that issued the token.
- The default expiry of a pairing token is 5 minutes.
- The token subject is the same as the subject of the principal who requested the pairing token.
- This token isrevocable and is expected to be used at most once (i.e., revoked after the first pairing)
- The base URL in the extension is mandatory and its goal is to assist services (instead of parsing and cutting the pairing URL to extract it). This is the same as expected to be defined for the request headerX-JFrog-Override-Base-Url
- The exchange URL in the extension is mandatory (since the token is signed, this URL can be assumed as trusted)
- The pairing URL is optional and is used when establishing two-way trust is needed.
The result of a pairing is themaster token. This access token grants the requesting service all the actions it is required to do on the issuing service, based on the given use case. It is usually a strong access token that can be used for several operations.
Create Pairing Token
This endpoint can be per use case or one for all (or some) use cases. The decision should be made based on service and use case requirements. The following definition is for an endpoint which serves several use cases.
Description: Creates a pairing token for a specific use case.
Since: 7.29.7
Authorization:Requires admin permissions.
Usage: POST /
The use-case in the usage above is perservice, per use case. For example:
- mission-control- for pairing an edge with Mission Control
- artifactory-cold- for establishing trust between "warm" and "cold" instances
- artifactory-cold/
- re-establish a revoked trust with a given namespace
Currently the only service (
Content-Type:application/json
Produces:application/json
Sample Usage:
POST /artifactory/api/v1/service_trust/pairing/{federated-repo/*} 200 { "pairing_token": "" }
Sample Response:
{ "ext": "{\"base_url\":\"http://localhost:9092\",\"exchange_url\":\"http://localhost:9092/artifactory/api/v1/service_trust/exchange\",\"revocable\":true}", "sub": "jfrt@01fnba8awk5na51pmjmjhm15qk/users/admin", "scp": "internal:service-trust/pairing/federated-repo/*:x", "aud": "jfrt@01fnba8awk5na51pmjmjhm15qk", "iss": "jfrt@01fnba8awk5na51pmjmjhm15qk/users/admin", "exp": 1637836575, "iat": 1637836275, "jti": "4be13896-2fef-418d-b07c-951cbd05ba71" }
Error Response Codes:
404Not found - the specified use case is unknown to the service
Initiate Pairing
Description: Initiates the pairing between the services. This endpoint can be per use case or one for all (or some) use cases.
Since: 7.29.7
Authorization: Requires admin permissions.
Usage: PUT /
- use_case=的用例创建配对托托en
- pairing_token= the pairing token the source service will use to initiate the pairing with the target. This is the same pairing token that wascreatedby the target of the pairing.
Content-Type: application/json
Produces:application/json
Sample Usage:
PUT /artifactory/api/v1/service_trust/pairing/{federated-repo/repokey} { "pairing_token": "" } 200 { "message": "Trust with Artifactory was established successfully" }
Error Response Codes:
404Not found - the specified use case is unknown to the service
Get Pairings
Description: Returns the list of target paired JPDs for a given use case.
Since: 7.29.7
Authorization: Requires admin permissions.
Usage:GET /
- use_case= the use case for which to get the pairings
- base_url= the base URL of the target, as provided in the pairing token
Content-Type: application/json
Produces:application/json
Sample Usage:
GET //api/v1/service_trust/pairings/{use-case} 200 [ { "base_url": " " }, ... ]
Success Response Codes:
200OK response with an empty list in case there are no paired targets for the given use case
Error Response Codes:
404Not found - the specified use case is unknown to the service
Enable Log Collection
Description:Enables log collection into a dedicated Logs Artifactory System Repository, to improve auditing capabilities.
Logs are collected in a dedicated system repository called
jfrog-logs.The repository will be created upon calling the API.
- Logs are collected in a cycle that may take up to 24 hours.
- By default, the log types collected are audit and request logs.
Available for Cloud subscriptions only.
Important
The data transfer and storage you consume for downloading or storing the logs will apply against your standard cloud usage, and may incur costs.
Since: 7.27.6
Security:Requires a validadmin-scoped token.
Authorization:Bearer
Usage:POST/access/api/v1/logshipping/config
Content-Type:application/json
Sample Usage
|
Example
curl -XPOST -H "Content-Type: application/json" -d'{"enabled": true}' -H "Authorization: Bearer " -v https:///access/api/v1/logshipping/config
Response Codes:
200OK
201Created
400 / 401Failureor unauthorized
PROJECTS
Base URL
/access/api #For example: http://ARTIFACTORY_SERVER_HOSTNAME:8082/access/api
Get Projects List
Description: Returns all projects the requesting user manages (Project Admin or a user assigned with the 'Administer the Platform' role).
Since: 7.17.4
Security: Requires a user with Project Admin or a user assigned with the 'Administer the Platform' role. Note that if the requestis issued by a Project Admin, only the projects listed under the Project Admin's scope will be listed.
Usage: GET${baseUrl}/access/api/v1/projects
Produces: application/json; charset=UTF-8
Header parameter:-H "Authorization: Bearer
[ { "display_name": "artifactory", "description": "The binary repository manager", "admin_privileges": { "manage_members": true, "manage_resources": true }, "storage_quota_bytes": 0, "soft_limit": false, "storage_quota_email_notification": true "project_key": "rtfct" } ]
Add a New Project
Description: Adds a new Project.
Since: 7.17.4
Security: Requires a user assigned with the 'Administer the Platform' role.
Usage: POST${baseUrl}/access/api/v1/projects
Produces: application/json; charset=UTF-8
Header parameter:授权:arer
Sample Request:
{ "display_name": "artifactory", "description": "The binary repository manager", "admin_privileges": { "manage_members": true, "manage_resources": true, "manage_security_assets": true, "index_resources": true, "allow_ignore_rules": true }, "storage_quota_bytes": 0, "project_key": "string" }
Sample Response:
{ "display_name": "artifactory", "description": "The binary repository manager", "admin_privileges": { "manage_members": true, "manage_resources": true, "manage_security_assets": true, "index_resources": true, "allow_ignore_rules": true }, "storage_quota_bytes": 0, "project_key": "string" }
Get Project
Description: Returns the desired project.
Since: 7.17.4
Security: Requires a user with Project Admin or a user assigned with the 'Administer the Platform' role.
Usage: GET${baseUrl}/access/api/v1/projects/{project_key}
Produces: application/json; charset=UTF-8
Header parameter:授权:arer
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
Sample Response:
{ "display_name": "artifactory", "description": "The binary repository manager", "admin_privileges": { "manage_members": true, "manage_resources": true }, "storage_quota_bytes": 0, "soft_limit": false, "storage_quota_email_notification": true "project_key": "string" }
Update Existing Project Properties
Description: Updates an existing project's properties.
Since: 7.17.4
Security: Requires a user assigned with the 'Administer the Platform' role permissions.
Usage: PUT${baseUrl}/access/api/v1/projects/{project_key}
Produces: application/json
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
(body) |
Project object that needs to be patched |
Header parameter:授权:arer
Sample Request:
{ "display_name": "project name", "description": "modified project description", "admin_priviledges": { "manage_members": true, "manage_resources": true, "index_resources": false }, "storage_quota_bytes": 10000, "soft_limit": false, "storage_quota_email_notification": true }
Sample Response:
{ "display_name": "artifactory", "description": "The binary repository manager", "admin_privileges": { "manage_members": true, "manage_resources": true }, "storage_quota_bytes": 0, "soft_limit": false, "storage_quota_email_notification": true "project_key": "rtfct" }
Delete Existing Project
Description:Deletes an existing project.
Since:7.17.4
Security:Requires a user assigned with the Administer the Platform role.
Usage:DELETE${baseUrl}/access/api/v1/projects/{project_key}
Produces:application/json
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
Header parameter:授权:arer
Sample Response:
Removed
Get Project Users
Description:Returns all users associated with the project.
Since:7.17.4
Security:Requires a user assigned with the Administer the Platform role or Project Admin permissions if `admin_privileges.manage_resources` is enabled.
Usage:GET${baseUrl}/access/api/v1/projects/{project_key}/users
Produces:application/json; charset=UTF-8
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
Header parameter:授权:arer
Sample Response:
[ { "name": "memberName", "roles": [ "developer" ] } ]
Get Project User
Description:Returns the requested user associated with the project.
Since: 7.17.4
Security:Requires a user assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resources` is enabled.
Usage:GET${baseUrl}/access/api/v1/projects/{project_key}/users/{user}
Produces:application/json; charset=UTF-8
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
(path) |
The user’s name |
Header parameter:授权:arer
Sample Response:
{" name": "memberName", "roles": [ "developer" ] }
Update User in Project
Description: Updates a user in a project.
Since:7.17.4
Security:Requires a user assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resoures` is enabled.
Usage:PUT${baseUrl}/access/api/v1/projects/{project_key}/users/{user}
Produces:application/json
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
(path) |
The user’s name |
(body) |
User object that needs to be added |
Header parameter:授权:arer
Sample Request:
{" name": "memberName", "roles": [ "developer" ] }
Sample Response:
{" name": "memberName", "roles": [ "developer" ] }
Delete Existing Project's User
Description:Deletes an existing project's user.
Since:7.17.4
Security:Requires a user assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resources` is enabled.
Usage: DELETE${baseUrl}/access/api/v1/projects/{project_key}/users/{user}
Produces:application/json
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
(path) |
The user’s name |
Header parameter:授权:arer
Sample Response:
Removed
Get Projects Groups
Description:Returns all groups associated with the project.
Since:7.17.4
Security:Requires a user assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resources` is enabled.
Usage:GET${baseUrl}/access/api/v1/projects/{project_key}/groups
Produces:application/json; charset=UTF-8
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
Header parameter:授权:arer
Sample Response:
[ { "name": "memberName", "roles": [ "developer" ] } ]
Get Projects Group
Description:Returns the requested group associated with the project.
Since:7.17.4
Security:Requires a user assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resources` is enabled.
Usage:GET${baseUrl}/access/api/v1/projects/{project_key}/groups/{group}
Produces:application/JSON; charset=UTF-8
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
(path) |
The group’s name |
Header parameter:授权:arer
Sample Response:
{" name": "memberName", "roles": [ "developer" ] }
Update Group in Project
Description:Updates the group in the project.
Since:7.17.4
Security:Requires a user assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resources` is enabled.
Usage:PUT${baseUrl}/access/api/v1/projects/{project_key}/groups/{group}
Produces:application/JSON
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
group* (path) |
The group’s name |
(body) |
group object that needs to be added |
Header parameter:授权:arer
Sample Request:
{" name": "memberName", "roles": [ "developer" ] }
Sample Response:
Updated group
Delete Existing Project's Group
Description:Deletes the existing project group.
Since:7.17.4
Security:Requires a user assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resources` is enabled.
Usage:DELETE${baseUrl}/access/api/v1/projects/{project_key}/groups/{group}
Produces:application/json
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
(path) |
The group’s name |
Header parameter:授权:arer
Sample Response:
Removed
Get Roles List
Description:Returns all project roles.
Since:7.17.4
Security:Requires a user assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resources` is enabled.
Usage:GET /v1/projects/{project_key}/roles
Produces:application/json; charset=UTF-8
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
Header parameter:授权:arer
Sample Response:
[ { "name": "senior developer", "actions": [ "READ_REPOSITORY" ], "type": "CUSTOM", "environments": [ "DEV" ] } ]
Add a New Role
Description:Adds a new role to the project.
Since:7.17.4
Security:Requires a user assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resoures` is enabled.
Usage:POST /v1/projects/{project_key}/roles
Produces:application/json
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
(body) |
role object that needs to be added |
Header parameter:授权:arer
Sample Request:
{" name": "senior developer", "actions": [ "READ_REPOSITORY" ], "type": "PREDEFINED", "environments": [ "DEV" ] }
Sample Response:
{" name": "senior developer", "actions": [ "READ_REPOSITORY" ], "type": "CUSTOM", "environments": [ "DEV" ] }
Get Project Role
Description:Returns the requested project role.
Since:7.17.4
Security:Requires a user with Project Admin or a users assigned with the 'Administer the Platform' role.
Usage:GET /v1/projects/{project_key}/roles/{role}
Produces:application/json; charset=UTF-8
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
(path) |
The role name |
Header parameter:授权:arer
Sample Response:
{" name": "senior developer", "actions": [ "READ_REPOSITORY" ], "type": "CUSTOM", "environments": [ "DEV" ] }
Update an Existing Project Role
Description:Updates an existing project role.
Since:7.17.4
Security:Requires a user assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resources` is enabled.
Usage:PUT /v1/projects/{project_key}/roles/{role}
Produces:application/json
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
(path) |
The role name |
(body) |
Role to be edited |
Header parameter:授权:arer
Sample Request:
{" name": "senior developer", "actions": [ "READ_REPOSITORY" ], "type": "PREDEFINED", "environments": [ "DEV" ] }
Sample Response:
{" name": "senior developer", "actions": [ "READ_REPOSITORY" ], "type": "CUSTOM", "environments": [ "DEV" ] }
Delete an Existing Role
Description:Deletes an existing role.
Since:7.17.4
Security:Requires a user with assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resource` is enabled.
Usage:DELETE /v1/projects/{project_key}/roles/{role}
Produces:application/json
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
(path) |
The role name |
Header parameter:授权:arer
Sample Response:
Deleted
Move Repository in a Project
Description:Moves the project repository to the specified location.
Since:7.17.4
Security:Requires a user assigned with the 'Administer the Platform' role.
Usage:PUT /v1/projects/_/attach/repositories/{repo_name}/{target_project_key}?force=true/false
Produces:application/json
Parameters:
| Name | Description |
|---|---|
(path) |
The project key |
(path) |
The repository name |
(query) |
Indicates a force move if the repo_name is already assigned to an actual project |
Header parameter:授权:arer
Sample Request
curl --location --request PUT '${baseUrl}/access/api/v1/projects/_/attach/repositories/{repo_name}/{target_project_key}?force=true/false' \ --header 'Authorization: Bearer '
Sample Response
Moved
Share Repository with All Projects
Description:Shares a local or remote repository across all the Projectsallowing members in more than one Project to have access to the repository.Project Members are granted actions to the shared repository according to their Roles and Role actions assigned in the target Project.
Since:7.15.3
Security:Requires a user assigned with the 'Administer the Platform' role.
Usage:PUT /v1/projects/_/share/repositories/{repo_name}
Parameters:
Name |
Description |
|---|---|
(path) |
The repository name |
Header parameter:授权:arer
Sample Request:
curl -X PUT "${baseUrl}/access/api/v1/projects/_/share/repositories/${repo_name}" -H "accept: application/json -H 'Authorization: Bearer "
Sample Response:
Shared
Unshare Repository with All Projects
Description:Unshares a shared local or remote repository. The repository is not deleted but remains assigned to the source repository.
Since:7.15.3
Security:Requires a user assigned with the 'Administer the Platform' role.
Usage:删除/ v1 /项目/ _ / /仓库/ {repo_nam分享e}
Parameters:
Name |
Description |
|---|---|
(path) |
The repository name |
Header parameter:授权:arer
Sample Request:
curl -X DELETE "${baseUrl}/access/api/v1/projects/_/share/repositories/${repo_name}" -H "accept: application/json -H 'Authorization: Bearer "
Sample Response:
UnShared
Share Repository with Target Project
Description:Shares a local or remote repository with a specific target Project.Project Members of the target project are granted actions to the shared repository according to their Roles and Role actions assigned in the target Project.
Since:7.15.3
Security:Requires a user assigned with the 'Administer the Platform' role.
Usage:PUT /v1/projects/_/share/repositories/{repo_name}/{target_project_key}
Name |
Description |
|---|---|
(path) |
The repository name |
(path) |
The Project Key |
Sample Request:
Header parameter:授权:arer
curl -X PUT "${baseUrl}/access/api/v1/projects/_/share/repositories/${repo_name}/{target_project_key}" -H "accept: application/json -H 'Authorization: Bearer "
Sample Response:
Shared
Unshare Repository with Target Project
Description: Unshares a local or remote repository with a specific target Project.
Since: 7.15.3
Security: Requires a user assigned with the 'Administer the Platform' role.
Usage:删除/ v1 /项目/ _ / /仓库/ {repo_nam分享e}/{target_project_key}
Name |
Description |
|---|---|
(path) |
The repository name |
(path) |
The Project Key |
Sample Request:
curl -X DELETE "${baseUrl}/access/api/v1/projects/_/share/repositories/${repo_name}/{target_project_key}" -H "accept: application/json -H 'Authorization: Bearer "
Sample Response:
Header parameter:授权:arer
Shared
Unassign a Project from a Repository
Description:Unassigns a project from a repository.
Notes:You can assign a Project to a repository using theMove Repositorycommand.
Since:7.17.1
Security:Requires a user assigned with the 'Administer the Platform' role or Project Admin permissions if `admin_privileges.manage_resource` is enabled.
Usage:DELETE ’${baseUrl}/access/api/v1/projects/_/attach/repositories/{repo_name}
Parameters:
Name |
Description |
|---|---|
| baseURL | |
| repo_name (path) |
The repository name |
Sample Request:
Header parameter:授权:arer
curl --location --request DELETE '${baseUrl}/access/api/v1/projects/_/attach/repositories/{repo_name} \ --header 'Authorization: Bearer '
Sample Response:
204
ROUTER
Base URL
: /router/api/v1 #For example: http://10.1.2.3:8082/router/api/v1
Health Check
Description: Get a simple status response about the state of a JFrog Product node.
Returnshealth state and general information regarding the router and locally registered services.
Since: Artifactory 7.0.0, Xray 3.0.0, Mission Control 4.0.0, Distribution 2.0.0, Pipelines 1.0.0
Security: No authentication required
Usage: GET/router/api/v1/system/health
Produces: application/json
Sample Output:
GET /路由器/ api / v1 /系统/卫生健康的反应:200 OK Content-Type: application/json { "router": { "node_id": "12345-defg-6789", "state": "HEALTHY", "message": "OK" }, "services": [ { "service_id": "jfsvc@123", "node_id": "12345-defg-6789", "state": "HEALTHY", "message": "OK" }, ... ] } Unhealthy Response: 503 SERVICE UNAVAILABLE Content-Type: application/json { "router": { "node_id": "12345-defg-6789", "state": "HEALTHY", "message": "OK" }, "services": [ { "service_id": "jfrt@1234", "node_id": "12345-defg-6789", "state": "UNHEALTHY_PEER", "message": "Service is healthy; there is at least one unhealthy service" },{ "service_id": "jffe@9876", "node_id": "12345-defg-6789", "state": "UNHEALTHY", "message": "Get http://localhost:3000/health: dial tcp 127.0.0.1:3000: connect: connection refused" }, ... ] }
WEBHOOKS
Base URL
/event/api/v1 #For example: http://ARTIFACTORY_SERVER_HOSTNAME:8082/event/api/v1
Get the List of all Webhook Subscriptions
Description: Returns all the configured Webhook subscriptions.
Security: Requires a valid admin user.
Usage: GET event/api/v1/subscriptions
Produces: application/json
Sample Output:
[{“关键”:“QaAudit”、“描述”:“触发QAaudit when a new artifact is created", "enabled": true, "event_filter": { "domain": "artifact", "event_types": [ "deployed" ], "criteria": { "anyLocal": true, "anyRemote": false, "includePatterns": [], "excludePatterns": [], "repoKeys": [] } }, "handlers": [ { "handler_type": "webhook", "url": "https://qa.my-company.test/", "secret": "tell no one", "proxy": "mainProxy", "custom_http_headers": [ { "name": "X-MyCompany-Header", "value": "whatever" } ] } ] }, { "key": "SecurityAudit", "description": "Triggers Security audit when a new artifact is deployed", "enabled": true, "event_filter": { "domain": "artifact", "event_types": [ "deployed" ], "criteria": { "anyLocal": true, "anyRemote": false, "includePatterns": [], "excludePatterns": [], "repoKeys": [] } }, "handlers": [ { "handler_type": "webhook", "url": "https://security.my-company.test/", "secret": "hush hush" } ] } ]
| Parameter | Description |
|---|---|
url |
Specifies the URL that the Webhook invokes. This will be the URL that Artifactory will send an HTTP POST request to. |
secret |
Defines a secret authentication token that will be sent to the configured URL. |
proxy |
Indicates whether to send the Webhook through a proxy. You can select a proxy from the configured proxy servers list. |
custom_http_headers |
Adds custom headers you wish to use to invoke the Webhook. crier |
criteria |
Specifies where the webhook will be applied, on which builds and repositories. Note: The supported format of |
Response Codes:
- 200List successfully provided
Create a New Webhook Subscription
Description: Registers a new Webhook subscription with a given input.
Security: Requires a valid admin user.
Usage: POST event/api/v1/subscriptions
Produces: application/json
Sample Input for Predefined Webhook:
{ "key": "Audits", "description": "Triggers Security and QA audits when a new artifact is created", "enabled": true, "event_filter": { "domain": "artifact", "event_types": [ "deployed", "moved", "copied" ], "criteria": { "anyLocal": true, "anyRemote": false, "includePatterns": [], "excludePatterns": [], "repoKeys": [] } }, "handlers": [ { "handler_type": "webhook", "url": "https://webhook.my-company.test/", "secret": "tell no one", "proxy": "mainProxy", "custom_http_headers": [ { "name": "X-MyCompany-Header", "value": "whatever" } ] } ] }
Sample Output for Predefined Webhook:
{ "key": "Audits", "description": "Triggers Security and QA audits when a new artifact is created", "enabled": true, "event_filter": { "domain": "artifact", "event_types": [ "deployed", "moved", "copied" ], "criteria": { "anyLocal": true, "anyRemote": false, "includePatterns": [], "excludePatterns": [], "repoKeys": [] } }, "handlers": [ { "handler_type": "webhook", "url": "https://webhook.my-company.test/", "secret": "tell no one", "proxy": "mainProxy", "custom_http_headers": [ { "name": "X-MyCompany-Header", "value": "whatever" } ] } ] }
When registering a Webhook subscription, the following elements are part of Artifactory itself;domain,event_typesandcriteriaand have the following valid values:
| domain | event-types | criteria |
|---|---|---|
artifact |
|
|
artifact_property |
|
|
docker |
|
|
build |
|
|
release_bundle |
|
|
distribution |
|
|
artifactory_release_bundle |
|
|
Sample Request for Custom Webhook:
{ "key": "trigger_action", "enabled": true, "event_filter": { "domain": "artifact", "event_types": [ "deployed" ], "criteria": { "anyLocal": true } }, "handlers": [ { "handler_type": "custom-webhook", "url": "https://api.github.com/repos/your/repo/actions/workflows/artifact_deployed.yml/dispatches", "payload": "{ \"ref\": \"main\" , \"inputs\": { \"artifact_path\": \"{{.data.repo_key}}/{{.data.path}}\" } }", "proxy": "mainProxy", "secrets": [ { "name": "token", "value": "***" } ], "http_headers": [ { "name": "Authorization", "value": "Bearer {{.secrets.token}}" }, { "name": "Accept", "value": "application/vnd.github+json" }, { "name": "Content-Type", "value": "application/json" } ] } ] }
| Parameter | Description |
|---|---|
url |
This is is the target URL that will get called. Example: |
http_headers |
This is the list of HTTP headers (name+value) that will be added to the request. |
payload |
This isused to build the request body. |
secrets |
This is a set of sensitive values that will be injected in the request (headers and/or payload). It is possible to update the value of a secret (when a password changes, or a token expires). The Webhook will fail if the token expires. In such cases, you must update the tokenusing the followingREST API call:
|
| proxy | Indicates whether to send the Webhook through a proxy. You can select a proxy from the configured proxy servers list. |
Sample Response for Custom Webhook:
{ "enabled": true, "event_filter": { "criteria": { "anyLocal": true }, "domain": "artifact", "event_types": [ "deployed" ] }, "handlers": [ { "handler_type": "custom-webhook", "http_headers": [ { "name": "Authorization", "value": "Bearer {{.secrets.token}}" }, { "name": "Accept", "value": "application/vnd.github+json" }, { "name": "Content-Type", "value": "application/json" } ], "payload": "{ \"ref\": \"main\" , \"inputs\": { \"artifact_path\": \"{{.data.repo_key}}/{{.data.path}}\" } }", "proxy": "mainProxy", "secrets": [ { "name": "token" } ], "url": "https://api.github.com/repos/your/repo/actions/workflows/artifact_deployed.yml/dispatches" } ], "key": "trigger_action" }
Response Codes:
- 201Success of creation
- 400Bad Input
- 409Subscription conflicts with an existing one (e.g key)
Get a Webhook Subscription by Key
Description: Get a Webhook subscription with a given key.
Security: Requires a valid admin user.
Usage: GET event/api/v1/subscriptions/{key}
Produces: application/json
Sample Output:
{ "key": "Audits", "description": "Triggers Security and QA audits when a new artifact is created", "enabled": true, "event_filter": { "domain": "artifact", "event_types": [ "deployed", "moved", "copied" ], "criteria": { "anyLocal": true, "anyRemote": false, "includePatterns": [], "excludePatterns": [], "repoKeys": [] } }, "handlers": [ { "handler_type": "webhook", "url": "https://webhook.my-company.test/", "secret": "tell no one", "proxy": "mainProxy", "custom_http_headers": [ { "name": "X-MyCompany-Header", "value": "whatever" } ] } ] }
Response Codes:
- 200Subscription description successfully provided
- 404Subscription does not exist
Update Webhook Subscription by Key
Description:Updates the Webhook subscription with a given key.
Security: Requires a valid admin user.
Usage: PUT event/api/v1/subscriptions/{key}
Produces: application/json
Sample Input:
{ "description": "Triggers Security and QA audits when a new artifact is created", "enabled": true, "event_filter": { "domain": "artifact", "event_types": [ "deployed", "moved", "copied" ], "criteria": { "anyLocal": true, "anyRemote": false, "includePatterns": [], "excludePatterns": [], "repoKeys": [] } }, "handlers": [ { "handler_type": "webhook", "url": "https://webhook.my-company.test/", "secret": "tell no one", "proxy": "mainProxy", "custom_http_headers": [ { "name": "X-MyCompany-Header", "value": "whatever" } ] } ] }
Response Codes:
- 204Success of update (no content)
- 400Bad input
- 404Subscription does not exist
删除Webhook订阅的关键
Description: Deletes the Webhook subscription with a given key.
Security: Requires a valid admin user.
Usage: DELETE event/api/v1/subscriptions/{key}
Produces: application/json
Response Codes:
- 204Success of deletion (no content)
- 404Subscription does not exist
Test Webhook Subscription
Description: Manually trigger a Webhook subscription with sample dataas if an event actually occurred. Subscription definition is given by the request payload.
Security: Requires a valid admin user.
Usage: POST event/api/v1/subscriptions/test
Produces: application/json
Sample Input:
{ "key": "Audits", "description": "Triggers Security and QA audits when a new artifact is created", "enabled": true, "event_filter": { "domain": "artifact", "event_types": [ "deployed", "moved", "copied" ], "criteria": { "anyLocal": true, "anyRemote": false, "includePatterns": [], "excludePatterns": [], "repoKeys": [] } }, "handlers": [ { "handler_type": "webhook", "url": "https://webhook.my-company.test/", "secret": "tell no one", "proxy": "mainProxy", "custom_http_headers": [ { "name": "X-MyCompany-Header", "value": "whatever" } ] } ] }
Sample Output:
{ "result": "success", "message": "Test is successful" }
Response Codes:
- 200Test was performed, a report (success or failure is provided in the response payload, including when the JFrog Service that should be the source of the event, is unreachable/unhealthy).
- 400Bad Input
Ping Request
Description:Sends a ping request tocheck if the microservice status.
Security:Requires an admin user.
Usage:GET /system/ping
Produces:text/plain
Sample usage:
|
