openapi: 3.1.0
info:
  title: JFrog Access REST API
  description: >-
    API for managing users, groups, permissions, projects, and access tokens
    across the JFrog Platform. JFrog Access handles identity management,
    role-based access control, federated identity, and scoped token creation
    for authentication and authorization across all JFrog services.
  version: 2.x
  contact:
    name: JFrog
    url: https://jfrog.com
  license:
    name: Proprietary
    url: https://jfrog.com/terms-of-service/
  termsOfService: https://jfrog.com/terms-of-service/
externalDocs:
  description: JFrog Access REST API Documentation
  url: https://jfrog.com/help/r/jfrog-platform-administration-documentation/access-token-rest-api
servers:
  - url: https://{server}.jfrog.io/access
    description: JFrog Cloud
    variables:
      server:
        default: myserver
        description: Your JFrog server name
  - url: https://{host}/access
    description: Self-hosted JFrog instance
    variables:
      host:
        default: localhost:8082
        description: Your self-hosted JFrog server host
security:
  - bearerAuth: []
  - basicAuth: []
tags:
  - name: Groups
    description: User group management
  - name: Permissions
    description: Permission target management
  - name: Projects
    description: Project administration
  - name: System
    description: Access service system information
  - name: Tokens
    description: Access token creation, management, and revocation
  - name: Users
    description: Platform user management
paths:
  /api/v1/system/ping:
    get:
      operationId: systemPing
      summary: JFrog System Ping
      description: Returns a simple health check response indicating the Access service is operational.
      tags:
        - System
      responses:
        '200':
          description: Access service is accessible
          content:
            text/plain:
              schema:
                type: string
                example: OK
  /api/v1/system/version:
    get:
      operationId: getSystemVersion
      summary: JFrog Get System Version
      description: Returns the Access service version and revision information.
      tags:
        - System
      responses:
        '200':
          description: Version information retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  version:
                    type: string
                  revision:
                    type: string
  /api/v2/tokens:
    get:
      operationId: listTokens
      summary: JFrog List Access Tokens
      description: >-
        Returns a list of all access tokens. Admin users see all tokens while
        non-admin users see only their own tokens.
      tags:
        - Tokens
      parameters:
        - name: subject
          in: query
          schema:
            type: string
          description: Filter tokens by subject
        - name: token_id
          in: query
          schema:
            type: string
          description: Filter by specific token ID
      responses:
        '200':
          description: Tokens list retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  tokens:
                    type: array
                    items:
                      $ref: '#/components/schemas/TokenInfo'
        '401':
          description: Unauthorized
    post:
      operationId: createToken
      summary: JFrog Create Access Token
      description: >-
        Creates a new scoped access token. Tokens can be scoped to specific
        resources, groups, and permissions. Supports creating user tokens,
        admin tokens, and project-scoped tokens.
      tags:
        - Tokens
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTokenRequest'
      responses:
        '200':
          description: Token created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '400':
          description: Invalid token configuration
        '401':
          description: Unauthorized
  /api/v2/tokens/{tokenId}:
    get:
      operationId: getToken
      summary: JFrog Get Token Details
      description: Returns metadata for a specific access token, not including the token value itself.
      tags:
        - Tokens
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
          description: Token ID
      responses:
        '200':
          description: Token details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenInfo'
        '404':
          description: Token not found
    delete:
      operationId: revokeToken
      summary: JFrog Revoke Access Token
      description: Revokes an existing access token, immediately invalidating it across all services.
      tags:
        - Tokens
      parameters:
        - name: tokenId
          in: path
          required: true
          schema:
            type: string
          description: Token ID
      responses:
        '200':
          description: Token revoked successfully
        '404':
          description: Token not found
  /api/v2/users:
    get:
      operationId: listUsers
      summary: JFrog List Users
      description: Returns a list of all platform users managed by the Access service.
      tags:
        - Users
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [enabled, disabled]
          description: Filter by user status
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
          description: Maximum number of results
        - name: offset
          in: query
          schema:
            type: integer
          description: Offset for pagination
      responses:
        '200':
          description: Users list retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
    post:
      operationId: createUser
      summary: JFrog Create User
      description: Creates a new platform user in the Access service identity store.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid user configuration
        '409':
          description: User already exists
  /api/v2/users/{username}:
    get:
      operationId: getUser
      summary: JFrog Get User
      description: Returns details for a specific user identified by username.
      tags:
        - Users
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
          description: Username
      responses:
        '200':
          description: User details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: User not found
    patch:
      operationId: updateUser
      summary: JFrog Update User
      description: Updates properties of an existing user. Only provided fields are updated.
      tags:
        - Users
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
          description: Username
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: User updated
        '404':
          description: User not found
    delete:
      operationId: deleteUser
      summary: JFrog Delete User
      description: Permanently deletes a user from the platform.
      tags:
        - Users
      parameters:
        - name: username
          in: path
          required: true
          schema:
            type: string
          description: Username
      responses:
        '204':
          description: User deleted
        '404':
          description: User not found
  /api/v2/groups:
    get:
      operationId: listGroups
      summary: JFrog List Groups
      description: Returns a list of all groups configured in the Access service.
      tags:
        - Groups
      responses:
        '200':
          description: Groups list retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  groups:
                    type: array
                    items:
                      $ref: '#/components/schemas/Group'
    post:
      operationId: createGroup
      summary: JFrog Create Group
      description: Creates a new group in the Access service for organizing users and assigning permissions.
      tags:
        - Groups
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
      responses:
        '201':
          description: Group created
        '400':
          description: Invalid group configuration
        '409':
          description: Group already exists
  /api/v2/groups/{groupName}:
    get:
      operationId: getGroup
      summary: JFrog Get Group
      description: Returns details for a specific group, including its members.
      tags:
        - Groups
      parameters:
        - name: groupName
          in: path
          required: true
          schema:
            type: string
          description: Group name
      responses:
        '200':
          description: Group details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
        '404':
          description: Group not found
    patch:
      operationId: updateGroup
      summary: JFrog Update Group
      description: Updates group properties. Only provided fields are modified.
      tags:
        - Groups
      parameters:
        - name: groupName
          in: path
          required: true
          schema:
            type: string
          description: Group name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Group'
      responses:
        '200':
          description: Group updated
        '404':
          description: Group not found
    delete:
      operationId: deleteGroup
      summary: JFrog Delete Group
      description: Deletes a group and removes all user associations.
      tags:
        - Groups
      parameters:
        - name: groupName
          in: path
          required: true
          schema:
            type: string
          description: Group name
      responses:
        '204':
          description: Group deleted
        '404':
          description: Group not found
  /api/v2/permissions:
    get:
      operationId: listPermissions
      summary: JFrog List Permissions
      description: Returns a list of all permission targets configured in the platform.
      tags:
        - Permissions
      responses:
        '200':
          description: Permissions list retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  permissions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Permission'
    post:
      operationId: createPermission
      summary: JFrog Create Permission
      description: >-
        Creates a new permission target defining access control rules for
        repositories, builds, and release bundles.
      tags:
        - Permissions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Permission'
      responses:
        '201':
          description: Permission created
        '400':
          description: Invalid permission configuration
        '409':
          description: Permission already exists
  /api/v2/permissions/{permissionName}:
    get:
      operationId: getPermission
      summary: JFrog Get Permission
      description: Returns the full configuration of a specific permission target.
      tags:
        - Permissions
      parameters:
        - name: permissionName
          in: path
          required: true
          schema:
            type: string
          description: Permission name
      responses:
        '200':
          description: Permission details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Permission'
        '404':
          description: Permission not found
    put:
      operationId: updatePermission
      summary: JFrog Update Permission
      description: Replaces the full configuration of an existing permission target.
      tags:
        - Permissions
      parameters:
        - name: permissionName
          in: path
          required: true
          schema:
            type: string
          description: Permission name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Permission'
      responses:
        '200':
          description: Permission updated
        '404':
          description: Permission not found
    delete:
      operationId: deletePermission
      summary: JFrog Delete Permission
      description: Removes a permission target and all its access control rules.
      tags:
        - Permissions
      parameters:
        - name: permissionName
          in: path
          required: true
          schema:
            type: string
          description: Permission name
      responses:
        '204':
          description: Permission deleted
        '404':
          description: Permission not found
  /api/v1/projects:
    get:
      operationId: listProjects
      summary: JFrog List Projects
      description: Returns a list of all projects in the platform.
      tags:
        - Projects
      responses:
        '200':
          description: Projects list retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
    post:
      operationId: createProject
      summary: JFrog Create Project
      description: Creates a new project with its own isolated resource scope and administration.
      tags:
        - Projects
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectRequest'
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '400':
          description: Invalid project configuration
        '409':
          description: Project key already exists
  /api/v1/projects/{projectKey}:
    get:
      operationId: getProject
      summary: JFrog Get Project
      description: Returns details for a specific project identified by its key.
      tags:
        - Projects
      parameters:
        - name: projectKey
          in: path
          required: true
          schema:
            type: string
          description: Project key
      responses:
        '200':
          description: Project details retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '404':
          description: Project not found
    put:
      operationId: updateProject
      summary: JFrog Update Project
      description: Updates project configuration and settings.
      tags:
        - Projects
      parameters:
        - name: projectKey
          in: path
          required: true
          schema:
            type: string
          description: Project key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectRequest'
      responses:
        '200':
          description: Project updated
        '404':
          description: Project not found
    delete:
      operationId: deleteProject
      summary: JFrog Delete Project
      description: Permanently deletes a project and disassociates all its resources.
      tags:
        - Projects
      parameters:
        - name: projectKey
          in: path
          required: true
          schema:
            type: string
          description: Project key
      responses:
        '204':
          description: Project deleted
        '404':
          description: Project not found
  /api/v1/projects/{projectKey}/users/{username}:
    put:
      operationId: addUserToProject
      summary: JFrog Add User to Project
      description: Adds a user to a project with specified role assignments.
      tags:
        - Projects
      parameters:
        - name: projectKey
          in: path
          required: true
          schema:
            type: string
          description: Project key
        - name: username
          in: path
          required: true
          schema:
            type: string
          description: Username to add
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                roles:
                  type: array
                  items:
                    type: string
                  description: Roles to assign (e.g., Project Admin, Developer, Viewer)
      responses:
        '200':
          description: User added to project
        '404':
          description: Project or user not found
    delete:
      operationId: removeUserFromProject
      summary: JFrog Remove User from Project
      description: Removes a user from a project, revoking all project-specific roles.
      tags:
        - Projects
      parameters:
        - name: projectKey
          in: path
          required: true
          schema:
            type: string
          description: Project key
        - name: username
          in: path
          required: true
          schema:
            type: string
          description: Username to remove
      responses:
        '204':
          description: User removed from project
        '404':
          description: Project or user not found
  /api/v1/projects/{projectKey}/groups/{groupName}:
    put:
      operationId: addGroupToProject
      summary: JFrog Add Group to Project
      description: Adds a group to a project with specified role assignments.
      tags:
        - Projects
      parameters:
        - name: projectKey
          in: path
          required: true
          schema:
            type: string
          description: Project key
        - name: groupName
          in: path
          required: true
          schema:
            type: string
          description: Group name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                roles:
                  type: array
                  items:
                    type: string
      responses:
        '200':
          description: Group added to project
    delete:
      operationId: removeGroupFromProject
      summary: JFrog Remove Group from Project
      description: Removes a group from a project.
      tags:
        - Projects
      parameters:
        - name: projectKey
          in: path
          required: true
          schema:
            type: string
          description: Project key
        - name: groupName
          in: path
          required: true
          schema:
            type: string
          description: Group name
      responses:
        '204':
          description: Group removed from project
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Access token authentication
    basicAuth:
      type: http
      scheme: basic
      description: Basic username/password authentication
  schemas:
    TokenInfo:
      type: object
      properties:
        token_id:
          type: string
          description: Unique token identifier
        subject:
          type: string
          description: Token subject (user or service)
        expiry:
          type: integer
          description: Token expiry timestamp (epoch seconds)
        issued_at:
          type: integer
          description: Token issuance timestamp (epoch seconds)
        issuer:
          type: string
          description: Token issuer service identifier
        description:
          type: string
          description: Human-readable token description
        refreshable:
          type: boolean
          description: Whether the token can be refreshed
        scope:
          type: string
          description: Token scope defining permissions
        audience:
          type: string
          description: Token audience
    CreateTokenRequest:
      type: object
      properties:
        subject:
          type: string
          description: 'Token subject in format: user/username or service/name'
        scope:
          type: string
          description: >-
            Space-separated scopes (e.g., "applied-permissions/user",
            "applied-permissions/admin", "applied-permissions/groups:readers,developers")
        expires_in:
          type: integer
          description: Token expiry in seconds (0 for non-expiring)
        refreshable:
          type: boolean
          description: Whether the token supports refresh
          default: false
        description:
          type: string
          description: Token description for management purposes
        audience:
          type: string
          description: Intended token audience
        include_reference_token:
          type: boolean
          description: Whether to include a reference token
          default: false
        project_key:
          type: string
          description: Project key to scope the token to a specific project
      required:
        - scope
    TokenResponse:
      type: object
      properties:
        token_id:
          type: string
        access_token:
          type: string
          description: The access token value (JWT)
        refresh_token:
          type: string
          description: Refresh token (if requested)
        expires_in:
          type: integer
          description: Token lifetime in seconds
        scope:
          type: string
        token_type:
          type: string
          example: Bearer
        reference_token:
          type: string
          description: Reference token (if requested)
    User:
      type: object
      properties:
        username:
          type: string
        email:
          type: string
          format: email
        admin:
          type: boolean
          description: Whether the user has admin privileges
        profile_updatable:
          type: boolean
          description: Whether the user can update their own profile
        disable_ui_access:
          type: boolean
          description: Whether UI access is disabled for this user
        internal_password_disabled:
          type: boolean
          description: Whether internal password authentication is disabled
        status:
          type: string
          enum: [enabled, disabled]
        groups:
          type: array
          items:
            type: string
          description: Groups the user belongs to
        realm:
          type: string
          description: Authentication realm (internal, ldap, saml, etc.)
        last_logged_in:
          type: string
          format: date-time
        created:
          type: string
          format: date-time
    CreateUserRequest:
      type: object
      properties:
        username:
          type: string
        email:
          type: string
          format: email
        password:
          type: string
        admin:
          type: boolean
          default: false
        profile_updatable:
          type: boolean
          default: true
        disable_ui_access:
          type: boolean
          default: false
        groups:
          type: array
          items:
            type: string
      required:
        - username
        - email
        - password
    UpdateUserRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        password:
          type: string
        admin:
          type: boolean
        profile_updatable:
          type: boolean
        disable_ui_access:
          type: boolean
        status:
          type: string
          enum: [enabled, disabled]
        groups:
          type: array
          items:
            type: string
    Group:
      type: object
      properties:
        name:
          type: string
          description: Unique group name
        description:
          type: string
        auto_join:
          type: boolean
          description: Whether new users automatically join this group
        admin_privileges:
          type: boolean
          description: Whether group members receive admin privileges
        realm:
          type: string
          description: Authentication realm for external groups
        external_id:
          type: string
          description: External identity provider group identifier
        members:
          type: array
          items:
            type: string
          description: List of usernames in the group
      required:
        - name
    Permission:
      type: object
      properties:
        name:
          type: string
          description: Unique permission target name
        resources:
          type: object
          description: Resource-level access control definitions
          properties:
            repository:
              type: object
              description: Repository-level permissions
              additionalProperties:
                type: object
                properties:
                  include_patterns:
                    type: array
                    items:
                      type: string
                  exclude_patterns:
                    type: array
                    items:
                      type: string
                  actions:
                    type: object
                    properties:
                      users:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                            enum: [read, write, annotate, delete, manage, managedXrayMeta, distribute]
                      groups:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
            build:
              type: object
              description: Build-level permissions
              additionalProperties:
                type: object
                properties:
                  include_patterns:
                    type: array
                    items:
                      type: string
                  exclude_patterns:
                    type: array
                    items:
                      type: string
                  actions:
                    type: object
                    properties:
                      users:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
                      groups:
                        type: object
                        additionalProperties:
                          type: array
                          items:
                            type: string
            releaseBundle:
              type: object
              description: Release bundle-level permissions
              additionalProperties:
                type: object
      required:
        - name
    Project:
      type: object
      properties:
        project_key:
          type: string
          description: Unique project key (max 32 chars)
          maxLength: 32
        display_name:
          type: string
        description:
          type: string
        admin_privileges:
          type: object
          properties:
            manage_members:
              type: boolean
            manage_resources:
              type: boolean
            manage_security_assets:
              type: boolean
            index_resources:
              type: boolean
            allow_ignore_rules:
              type: boolean
        max_storage_in_gibibytes:
          type: integer
        soft_limit:
          type: boolean
        storage_quota_bytes:
          type: integer
        storage_quota_email_notification:
          type: boolean
    ProjectRequest:
      type: object
      properties:
        project_key:
          type: string
          maxLength: 32
        display_name:
          type: string
        description:
          type: string
        admin_privileges:
          type: object
          properties:
            manage_members:
              type: boolean
            manage_resources:
              type: boolean
            manage_security_assets:
              type: boolean
            index_resources:
              type: boolean
            allow_ignore_rules:
              type: boolean
        max_storage_in_gibibytes:
          type: integer
      required:
        - project_key
        - display_name