JFrog Help Center

Our new portal is coming soon!
Documentation + Knowledge Base





JFrog Help Center - A new knowledge experience is coming your way soon!



Usage

The JFrog Platform REST API endpoints can be invoked in any of the standard ways to invoke a RESTful API. This section describes how to use the Platform REST API using cURL as an example.

Using and Configuring cURL

Example: /repo-key/path/to/artifact.ext

You can download cURL here. and learn how to use and configure cURL here.

Authentication

JFrog Platform's REST API supports these forms of authentication:

  • Basic authentication using your username and password
  • Using an access token instead of a password for basic authentication.
  • Using an access token as a bearer token in an authorization header (Authorization: Bearer) with your access token.

Base URL

The REST URL is constructed of: 

 Code Block
http://<JFROG_PLATFORM_URL>:<ROUTER_PORT>/access/api/v1/

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://<Server Name>.jfrog.io/artifactory/

Example

The snippets below apply the same example described above to an Artifactory Cloud instance named "myArtifactoryCloud" (instead of to a self-hosted installation).

To deploy the file using your username and password for authentication, you would use the following command:

Using cURL with the REST API for Artifactory Cloud
curl -u myUser:myP455w0rd! -X PUT "https://myartifactorycloud.jfrog.io/artifactory/my-repository/my/new/artifact/directory/file.txt" -T Desktop/myNewFile.txt
Using JFrog CLI
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 to configure JFrog CLI with 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, see ERROR RESPONSES in the JFrog Artifactory REST APIs.

Usage of REST resources is subject to security restrictions applicable to each individual resource.

Page Contents

 




SECURITY

The Security APIs, available from Artifactory release 7.49.3, replace the previous Security 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:

StringDescription
RealmAn enum string with the possible values: internal, saml, oauth, ldap, crowd, scim, etc.
StatusAn enum string with the possible values: invited, enabled, disabled, locked
uriA uri string to the Get Username endpoint

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 the result 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 parameter realm will 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"
}

Response Codes:

  • 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:

StringDescription
RealmAn enum string with the possible values: internal, saml, oauth, ldap, crowd, scim, etc.
StatusAn enum string with the possible values: invited, enabled, disabled, locked
uriA uri string to the Get Group Details endpoint.

Get Group Details

Description: Returns the groups' details based 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 the result 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)

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: 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" : "<The URL that Artifactory should connect to>",
  -  "username" : "<Username to be used for the connection test>",
  -  "password" : "<Password to be used for the connection test>"
}

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 paste http://www.jfrog.org/xsd/artifactory-v1_7_3.xsd to a new tab in your brower.

To
Sample Output:

GET /api/system/configuration

<artifactory.config.xml/>

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 paste http://www.jfrog.org/xsd/artifactory-v1_7_3.xsd to a new tab in your brower.


Sample Usage:

POST /api/system/configuration

<artifactory.config.xml/>

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": "<supplied license key>"         // 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
Producesapplication/json

[ {
  	"type" : "Enterprise",
  	"validThrough" : "<validity date formatted MMM DD, YYYY>",
  	"licensedTo" : "<Company name>",
  	"licenseHash" : "<license hash code>",
  	"nodeId" : "<Node ID of the node activated with this license | Not in use>",
  	"nodeUrl" : "<URL of the node activated with this license | Not in use>",
  	"expired" : <true | false>
}]


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": "<supplied license key>"         // Any newline characters must be represented by escape sequence (\n)
}]

Producesapplication/json

{
 "status" : 200,
  "messages" : {
    ["<License key>" : "<status message>"] 
 }

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" : {["<License hash code>" : "<status message>"]}
}

 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
Producesapplication/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 user and 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.
UsageGET /api/system/configuration/webServer
Produces: application/json
Sample Output:

GET /api/system/configuration/webServer

{
  "key" : "nginx",
  "webServerType" : "NGINX",
  "artifactoryAppContext" : "artifactory",
  "publicAppContext" : "artifactory",
  "serverName" : "jfrog.com",
  "serverNameExpression" : "*.jfrog.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 the dockerReverseProxyMethod from the JFrog Platform UI to the Reverse Proxy API:

UI ValueAPI Value
Subdomain

SUBDOMAIN

Repository PathREPOPATHPREFIX
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" : "jfrog.com",
  "serverNameExpression" : "*.jfrog.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 ~(?<repo>.+)\.jfrog.com jfrog.com;
    
    if ($http_x_forwarded_proto = '') {
        set $http_x_forwarded_proto  $scheme;
    }
    ## Application specific logs
    ## access_log /var/log/nginx/jfrog.com-access.log timing;
    ## error_log /var/log/nginx/jfrog.com-error.log;
    rewrite ^/$ /artifactory/webapp/ redirect;
    rewrite ^/artifactory$ /artifactory/webapp/ redirect;
}

Start SHA256 Migration Task

Description: Starts the SHA-256 migration process.
Note: Migration can also be configured using a set of properties in Artifactory's artifactory.system.properties file.
Security: Administrator permissions
Usage: POST api/system/migration/sha2/start 
Since: 6.6.0
Consumesapplication/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 the SHA-256 migration process
Security: Administrator permissions
Note: The sleepIntervalMillis should match what was defined in the Start SHA256 Migration Task
Usage: POST api/system/migration/sha2/stop?{sleepIntervalMillis=5000} 
Producestext/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" : "<Location on primary node where bootstrap bundle was created>"
}

Sample usage:

POST /api/system/bootstrap_bundle
 
{
  "file" : "/opt/jfrog/artifactory/etc/bootstrap.bundle.tar.gz"
}

Re-index paths on Metadata Server 

DescriptionIf 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. Asynchronous by 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]
Consumesapplication/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, see Artifactory 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

Consumesapplication/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":"<name of support bundle>",
   "description":"<desc of support bundle>",
   "parameters":{  
      "configuration": "<true | false>",       // Default: true.
      "system": "<true | false>",              // Default: true.
      "logs":{  
         "include": "<true | false>",          // Default: true.
         "start_date":"<start date from which to fetch the logs. pattern: YYYY-MM-DD>",
         "end_date":"<end date until which to fetch the logs. pattern: YYYY-MM-DD>"
      },
      "thread_dump":{  
         "count": <number of times to collect thread dump. Default:1>,
         "interval": <Interval between times of collection in milliseconds. Default:0>
      }
   }
}

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

<JFrog 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 valid admin-scoped token. The API no longer supports basic authentication.

  
Usage: POST /api/v1/system/backup/export
Sample Usage:

curl -H "Authorization: Bearer <Token>" -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 valid admin-scoped token. The API no longer supports basic authentication.

  
Usage: POST /api/v1/system/backup/import
Sample Usage:

curl -H "Authorization: Bearer <Token>" -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 valid admin-scoped token. The API no longer supports basic authentication.

  
Usage: GET /system/ping
Produces: text/plain
Sample usage:

curl -H "Authorization: Bearer <Token>" 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 valid admin-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 <Token>" http://localhost:8082/access/api/v1/cert/root
or
curl -H "Authorization: Bearer <Token>" 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 valid admin-scoped token. The API no longer supports basic authentication.  

Usage: GET /api/v1/system/federation

Produces: text/plain

Sample Usage

curl -H "Authorization: Bearer <Token>" GET "http://localhost:8082/access/api/v1/system/federation/" -H "accept: application/json"

Response Codes: 

200 Successful operation

200 Successful 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 / 403 Unauthenticated 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 valid admin-scoped token. The API no longer supports basic authentication.  

Usage: POST /api/v1/system/federation
Produces: text/plain
Sample usage:

curl -H "Authorization: Bearer <Token>" 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:

201 Successfully registered

 {
  "name": "access-2",
  "url": "https://access.example.com/access/",
  "entities": [
    "users",
    "groups",
    "permissions"
  ],
  "permissionFilters": {
    "includePatterns": [
      "team_a_*"
    ],
    "excludePatterns": [
      "none_federated_*"
    ]
  },
  "active": true
}

400 Invalid input

401 Unauthorized

403 Forbidden

404 Already 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 valid admin-scoped token. The API no longer supports basic authentication.  

Usage: GET /api/v1/system/federation/{server_name}

Produces: text/plain

Sample Usage

curl -H "Authorization: Bearer <Token>" GET "http://localhost:8082/access/api/v1/system/federation/{server_name}" -H "accept: application/json"

Response Codes: 

200 Successful operation

200 Successful operation
{
  "name": "access-2",
  "url": "https://access.example.com/access/",
  "entities": [
    "users",
    "groups",
    "permissions"
  ],
  "permissionFilters": {
    "includePatterns": [
      "team_a_*"
    ],
    "excludePatterns": [
      "none_federated_*"
    ]
  },
  "active": true
}

401 Unauthorized
403 Forbidden
404 No 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 valid admin-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 <Token>" DELETE "http://localhost:8082/access/api/v1/system/federation/{server_name}" -H "accept: application/json"

Response Codes: 

204 Successfully unregistered
401 Unauthorized
403 
Forbidden
404 
No 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 valid admin-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 <Token>" 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: 
204
Successful operation

{
  "name": "access-2",
  "url": "https://access.example.com/access/",
  "entities": [
    "users",
    "groups",
    "permissions"
  ],
  "permissionFilters": {
    "includePatterns": [
      "team_a_*"
    ],
    "excludePatterns": [
      "none_federated_*"
    ]
  },
  "active": true
}

400 Invalid input
401 Unauthorized
403 Forbidden


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 valid admin-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 <Token>" 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: 

204 Successfully validated

400 Invalid input

401 Unauthorized

403 Forbidden

412 Precondition 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 valid admin-scoped token. The API no longer supports basic authentication.  

Usage: PUT /api/v1/system/federation/<federation_target_servername>/full_broadcast
Produces: text/plain
Sample usage:

curl -H "Authorization: Bearer <Token>" http://localhost:8082/access/api/v1/system/federation/<Access Service ID - Ex: "jfac@abc[...]123">/full_broadcast -XPUT

Response Codes: 
204
Successful operation

Description: Invokes Access Federation full broadcast from a single federation source to all its federation targets.  This API targets the server's access_id.

You can obtain the access_id from the source's access.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 valid admin-scoped token. The API no longer supports basic authentication.  

Usage: PUT /api/v1/system/federation/<federation_target_servername>/full_broadcast
Produces: text/plain
Sample usage:

curl -H "Authorization: Bearer <Token>" http://localhost:8082/access/api/v1/system/federation/<federation_target_access_id>/full_broadcast -XPUT

For example:

curl -H "Authorization: Bearer <Token>" http://localhost:8082/access/api/v1/system/federation/jfac@01ep443hcx10x00djcdsp31d56/full_broadcast -XPUT

Response Codes: 

204 Successful 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/<id>
Produces: application/scim+json; charset=UTF-8
Header parameter: Authorization: Bearer
Sample response:

200 - OK - user exists
{
   "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:

200 - OK - 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 of filter=userName eq "username"

UsageGET /api/v1/scim/v2/Users

Query parameters (optional)?filter=userName eq “username”

Produces: application/scim+json; charset=UTF-8
Header parameter: Authorization: Bearer
Sample response:

200 - OK - user exists
{
   "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:

200 - OK - 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: Authorization: Bearer
Sample response:

201 - Created
{
   "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/<id>
Consumes: application/scim+json; charset=UTF-8
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: Authorization: Bearer 
Sample response: 

200 - OK
{
  "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/<id>
Consumes: application/scim+json; charset=UTF-8
Sample request:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [{
    "op": "Replace",
    "path": "active",
    "value": false
  }]
}

Produces: application/scim+json; charset=UTF-8
Header parameter: Authorization: Bearer
Sample response:

200 - OK
{
  "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/<id>
Header parameter: Authorization: Bearer 
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 contain all groups (limited to the first 20).

Usage: GET /api/v1/scim/v2/Groups?filter = displayName eq “groupName”

Produces: application/scim+json; charset=UTF-8

Header parameter: Authorization: Bearer

Sample response:

200 - OK - group exists
[
  {
    "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:

200 - OK - 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/<groupName>

Produces: application/scim+json; charset=UTF-8

Header parameter: Authorization: Bearer

Sample response:

200 - OK - group exists
{
   "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 - Group not found
{
   "status": 404,
   "detail": "examplesgroup isn't found",
   "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: 

201- created
{
   "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 only adding/removing members from the group.

Description: This API allows to add or remove members from the group.

Usage: PUT /api/v1/scim/v2/Groups/<groupName>

Header parameter: Authorization: Bearer 

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

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/<groupName>

Header parameter: Authorization: Bearer

Consumes: application/scim+json; charset=UTF-8

Sample request:

{
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
   "Operations": [{
       "op": "Add",
       "path": "members",
       "value": [{
           "$ref": null,
           "value": "newMember"
       }]
   }]
}

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"
   }
}



Delete Group

Description: This API will delete a single group.

Usage: DELETE /api/v1/scim/v2/Groups/<groupName>

Header parameter: Authorization: Bearer 

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 allows users 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, the default expiry 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.
  • Must comply with ('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 the max 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.
  • Must comply with ('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-urlencoded or application/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/user then 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_credentials for 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_revocable in the Create Token REST API. When this parameter is set to true, we will add the force_revocable flag to the token's extension.
    In addition, a new configuration has been added that sets the default for setting the force_revocable default 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 <valid access token>" -XPOST "http://localhost:8082/access/api/v1/tokens" -d "scope=applied-permissions/user" 
 
200
{
  "token_id": "<id>"
  "access_token": "<access-token>",
  "refresh_token": "<refresh-token>",  // optional
  "expires_in": "<seconds>",             // optional      
  "scope": "applied-permissions/groups:<group-name>" 
  "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]
The user name for which this token is created. The username is based on the authenticated user - either from the user of the authenticated token or based on the username (if basic auth was used). The username is then used to set the subject of the token: <service-id>/users/<username>
Limited to 255 characters.

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 create Identity Tokens (user scope).

The supported scopes include:

  • applied-permissions/user - provides user access. If left at the default setting, the token will be created with the user-identity scope, which allows users to identify themselves in the Platform but does not grant any specific access permissions.
  • applied-permissions/admin - the scope assigned to admin users.
  • applied-permissions/groups - this scope assigns permissions to groups using the following format: applied-permissions/groups:<group-name>[,<group-name>...]
  • system:metrics:r - for getting the service metrics
  • system:livelogs:r - for getting the service livelogsr

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 amount of time, in seconds, it would take for the token to expire. 
An admin shall be able to set whether expiry is mandatory, what is the default expiry, and what is the maximum expiry allowed.

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.
Limited to 1024 characters.

audience

[Optional, default: *@*]

A space-separated list of the other instances or services that should accept this token identified by their Service-IDs.

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_in value is not a number, non-positive number, etc.
  • 401 - Unauthenticated
  • 403 - The requested token details are forbidden, e.g. expires_in provided 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": "<id>",
      "subject": "<subject>",
      "expiry": <epoch-in-secs>,       // optional
      "issued_at": <epoch-in-secs>,
      "issuer": "<issuer>",
      "description": "<description>",  // optional
      "refreshable": <true|false>
    }, 
    ...
  ]
}
  • 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 an empty list of tokens.
  • Supports query parameters to filter the response:
    • description=<description> (supports wildcard, the wildcard must to be at the end of the text)
    • refreshable=<true|false>

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 <valid access token>" "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/{id}
Produces: application/json 

{
  "token_id": "<id>",
  "subject": "<subject>",
  "expiry": <epoch-in-secs>,       // optional
  "issued_at": <epoch-in-secs>,
  "issuer": "<issuer>",
  "description": "<description>",  // optional
  "refreshable": <true|false>
}

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/{id}
Produces: application/json 
Sample Usage:

curl -H "Authorization: Bearer <valid access token>" -XDELETE "http://localhost:8082/access/api/v1/tokens/7e0eec..."  
 
200 OK

This endpoint can take either of the following parameters:

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 token can be 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 token without 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: <authorization header value>
Content-Type: application/x-www-form-urlencoded
Produces: application/json (see Create 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": "<id>"
  "access_token": "<access-token>",
 // optional
  "expires_in": <expiry>,              // optional
  "grant_type": "refresh_token",
  "refresh_token": "<refresh-token>" 
}

This endpoint takes the following parameters:

grant_type

Should be set to refresh_token

refresh_token
The value of refresh token of the access token that needs to be refreshed: <refresh-token>

For all other parameters, see Create 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 is revocable 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 header X-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 the master 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 /<svc>/api/v1/service_trust/pairing/{use-case}

The use-case in the usage above is per service, 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/<ns> - re-establish a revoked trust with a given namespace

Currently the only service (<svc>) that is supported is Artifactory.

Content-Type: application/json
Produces:
application/json
Sample Usage:

POST /artifactory/api/v1/service_trust/pairing/{federated-repo/*}
200
{
  "pairing_token": "<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:

404 Not 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 /<svc>/api/v1/service_trust/pairing/{use-case}

  • use_case = the use case for which to create the pairing token
  • pairing_token = the pairing token the source service will use to initiate the pairing with the target. This is the same pairing token that was created by 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": "<pairing-token>"
}

200
{
  "message": "Trust with Artifactory was established successfully"
}

Error Response Codes:

404 Not 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 /<svc>/api/v1/service_trust/pairings/{use-case}

  • 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 /<svc>/api/v1/service_trust/pairings/{use-case}

200
[
  {
    "base_url": "<base-url>"
  }, ...
]

Success Response Codes:

200 OK response with an empty list in case there are no paired targets for the given use case

Error Response Codes:

404 Not 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
SecurityRequires a valid admin-scoped token.  
AuthorizationBearer
Usage: POST/access/api/v1/logshipping/config
Content-Type: application/json
Sample Usage

{"enabled": true/false}

Example

curl -XPOST  -H "Content-Type: application/json" -d'{"enabled": true}' -H "Authorization: Bearer <ADMIN ACCESS-TOKEN>" -v https://<JFROG_PLAFORM_URL>/access/api/v1/logshipping/config 

Response Codes: 

200 OK

201 Created

400 / 401 Failure or unauthorized

PROJECTS

Base URL

<JFrog 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 request is 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 <ACCESS_TOKEN>"
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"
  }
]

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: Authorization: Bearer
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: Authorization: Bearer
Parameters:

NameDescription

project_key *
string

(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:

NameDescription

project_key *
string

(path)

The project key

body *

(body)

Project object that needs to be patched

Header parameter: Authorization: Bearer
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

NameDescription

project_key *
string

(path)

The project key

Header parameter: Authorization: Bearer
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: 

NameDescription

project_key *
string

(path)

The project key

Header parameter: Authorization: Bearer
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: 

NameDescription

project_key *
string

(path)

The project key

user *
string

(path)

The user’s name

Header parameter: Authorization: Bearer
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:

NameDescription

project_key *
string

(path)

The project key

user *
string

(path)

The user’s name

body *

(body)

User object that needs to be added

Header parameter: Authorization: Bearer
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:

NameDescription

project_key *
string

(path)

The project key

user *
string

(path)

The user’s name

Header parameter: Authorization: Bearer
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:

NameDescription

project_key *
string

(path)

The project key

Header parameter: Authorization: Bearer
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:

NameDescription

project_key *
string

(path)

The project key

group *
string

(path)

The group’s name

Header parameter: Authorization: Bearer
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:

NameDescription

project_key *
string

(path)

The project key

group *
string

(path)

The group’s name

body *

(body)

group object that needs to be added

Header parameter: Authorization: Bearer
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:

NameDescription

project_key *
string

(path)

The project key

group *
string

(path)

The group’s name

Header parameter: Authorization: Bearer
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:

NameDescription

project_key *
string

(path)

The project key

Header parameter: Authorization: Bearer
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:

NameDescription

project_key *
string

(path)

The project key

body *

(body)

role object that needs to be added

Header parameter: Authorization: Bearer
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:

NameDescription

project_key *
string

(path)

The project key

role *
string

(path)

The role name

Header parameter: Authorization: Bearer
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:

NameDescription

project_key *
string

(path)

The project key

role *
string

(path)

The role name

body *

(body)

Role to be edited

Header parameter: Authorization: Bearer
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:

NameDescription

project_key *
string

(path)

The project key

role *
string

(path)

The role name

Header parameter: Authorization: Bearer
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:

NameDescription

target_project_key *
string

(path)

The project key

repo_name *

(path)

The repository name

force

(query)

Indicates a force move if the repo_name is already assigned to an actual project

Header parameter: Authorization: Bearer
Sample Request

curl --location --request PUT '${baseUrl}/access/api/v1/projects/_/attach/repositories/{repo_name}/{target_project_key}?force=true/false' \
--header 'Authorization: Bearer <a valid access-token>'

Sample Response

Moved

Share Repository with All Projects

Description: Shares a local or remote repository across all the Projects allowing 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

repo_name *
string

(path)

The repository name

Header parameter: Authorization: Bearer
Sample Request:

curl -X PUT "${baseUrl}/access/api/v1/projects/_/share/repositories/${repo_name}" -H "accept: application/json -H 'Authorization: Bearer <a valid access-token>"

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: DELETE /v1/projects/_/share/repositories/{repo_name}
Parameters:

Name

Description

repo_name *
string

(path)

The repository name

Header parameter: Authorization: Bearer
Sample Request:

curl -X DELETE "${baseUrl}/access/api/v1/projects/_/share/repositories/${repo_name}" -H "accept: application/json -H 'Authorization: Bearer <a valid access-token>"

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

repo_name *
string

(path)

The repository name

target_project_key * 

(path)

The Project Key

Sample Request:
Header parameter: Authorization: Bearer

curl -X PUT "${baseUrl}/access/api/v1/projects/_/share/repositories/${repo_name}/{target_project_key}" -H "accept: application/json -H 'Authorization: Bearer <a valid access-token>"

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.
UsageDELETE /v1/projects/_/share/repositories/{repo_name}/{target_project_key}

Name

Description

repo_name *
string

(path)

The repository name

target_project_key * 

(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 <a valid access-token>"

Sample Response:
Header parameter: 
Authorization: Bearer

Shared



Unassign a Project from a Repository

Description: Unassigns a project from a repository.
Notes: You can assign a Project to a repository using the Move Repository command.
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: 
Authorization: Bearer

curl --location --request DELETE '${baseUrl}/access/api/v1/projects/_/attach/repositories/{repo_name} \
--header 'Authorization: Bearer <a valid access-token>'

Sample Response:

204



ROUTER

Base URL

<node IP>:<Router Port>/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.
Returns health 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 /router/api/v1/system/health

Healthy Response:
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

<JFrog 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:

[
  {
    "key": "QaAudit",
    "description": "Triggers QA audit 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"
      }
    ]
  }
]
ParameterDescription
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 includePatterns and excludePatterns is ANT pattern.

Response Codes: 

  • 200 List 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_types and criteria and have the following valid values:

domainevent-typescriteria
artifact
  • deployed
  • deleted
  • moved
  • copied
  • anyLocal
  • anyRemote
  • includePatterns
  • excludePatterns
  • repoKeys


artifact_property
  • added
  • deleted
docker
  • pushed
  • deleted
  • promoted
build
  • uploaded
  • deleted
  • promoted
  • anyBuild
  • selectedBuilds
  • includePatterns
  • excludePatterns
release_bundle
  • created
  • signed
  • deleted
  • anyReleaseBundle
  • includePatterns
  • excludePatterns
  • registeredReleaseBundlesNames
distribution
  • distribute_started
  • distribute_completed
  • distribute_aborted
  • distribute_failed
  • delete_started
  • delete_completed
  • delete_failed
  • anyReleaseBundle
  • includePatterns
  • excludePatterns
  • registeredReleaseBundlesNames
artifactory_release_bundle
  • received
  • delete_started
  • delete_completed
  • delete_failed
  • anyReleaseBundle
  • includePatterns
  • excludePatterns
  • registeredReleaseBundlesNames

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"
               }
           ]
       }
   ]
}

ParameterDescription

url

This is is the target URL that will get called.

Example: https://api.github.com/repos/your/repo/actions/workflows/artifact_deployed.yml/dispatches

http_headers

This is the list of HTTP headers (name+value) that will be added to the request.

payload

This is used 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 token using the following REST API call:

PUT /event/api/v1/subscriptions/<sub-key>/secrets/<secret-name>


Authorization : Bearer <admin token>
Content-Type : text/plain
< secret-value>

proxyIndicates 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: 

  • 201 Success of creation
  • 400 Bad Input
  • 409 Subscription 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:

  • 200 Subscription description successfully provided
  • 404 Subscription does not exist


Update Webhook Subscription by Key 

DescriptionUpdates 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:

  • 204 Success of update (no content)
  • 400 Bad input
  • 404 Subscription does not exist

Delete Webhook Subscription by Key

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:

  • 204 Success of deletion (no content)
  • 404 Subscription does not exist

Test Webhook Subscription

Description: Manually trigger a Webhook subscription with sample data as 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:

  • 200 Test 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).
  • 400 Bad Input

Ping Request

Description: Sends a ping request to check if the microservice status.
Security: Requires an admin user. 
Usage: GET /system/ping
Produces: text/plain
Sample usage:

curl -uadmin:password http://localhost:8082/access/api/v1/system/ping



Copyright © 2023 JFrog Ltd.