Newstore roles API

openapi: 3.2.0
info:
  version: '1.0'
  title: NewStore Roles API
  description: NewStore public APIs
  contact:
    email: support@newstore.com
    name: NewStore API Support
    url: https://developer.newstore.com
servers:
- url: https://dodici-demo.p.newstore.net/
security: []
tags:
- name: roles
  description: Roles
paths:
  /iam/permissions:
    get:
      description: Lists all the user permissions available for the retailer.
      summary: listPermissions
      tags:
      - roles
      operationId: listPermissions
      deprecated: false
      responses:
        default:
          description: Default response
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: Returns all permissions.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/GetPermissionsResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/GetPermissionsResponse'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal server error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - iam:roles:read
  /iam/roles:
    get:
      description: Lists all available user roles for the retailer. Search if the query parameter is used.
      summary: listRoles
      tags:
      - roles
      operationId: listRoles
      deprecated: false
      parameters:
      - name: q
        in: query
        required: false
        description: Query the resulting list by name.
        schema:
          type: string
      responses:
        default:
          description: Default response
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: Returns all roles.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/GetRolesResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/GetRolesResponse'
        '400':
          description: Bad Request, invalid query parameters.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal server error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - iam:roles:read
    post:
      description: Creates a new role.
      summary: createRole
      tags:
      - roles
      operationId: createRole
      deprecated: false
      parameters:
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Default response
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '201':
          description: The role is created.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Role'
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '400':
          description: Bad Request, invalid request body.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: The provided name is already in use.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '412':
          description: One or more permissions used were not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal server error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - iam:roles:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRolesRequest'
        required: true
  /iam/roles/{id}:
    delete:
      description: 'Deletes the user role with the specified ID.


        Once deleted, the user role is unassigned from all associated user accounts.

        '
      summary: destroyRole
      tags:
      - roles
      operationId: destroyRole
      deprecated: false
      parameters:
      - name: id
        in: path
        required: true
        description: role id
        schema:
          type: string
      responses:
        default:
          description: Default response
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '204':
          description: The deletion request was sucessful.
          headers: {}
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Role was not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '423':
          description: Cannot delete a read-only role.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal server error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - iam:roles:write
    get:
      description: Retrieves the user role with the specified ID.
      summary: showRole
      tags:
      - roles
      operationId: showRole
      deprecated: false
      parameters:
      - name: id
        in: path
        required: true
        description: role id
        schema:
          type: string
      responses:
        default:
          description: Default response
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: ''
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Role'
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Role not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal server error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - iam:roles:read
    put:
      description: Updates the user role with the specified ID.
      summary: replaceRole
      tags:
      - roles
      operationId: replaceRole
      deprecated: false
      parameters:
      - name: id
        in: path
        required: true
        description: role id
        schema:
          type: string
      - name: Content-Type
        in: header
        required: false
        description: ''
        schema:
          type: string
          enum:
          - application/json
      responses:
        default:
          description: Default response
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: The updated role.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Role'
            application/json:
              schema:
                $ref: '#/components/schemas/Role'
        '400':
          description: Bad Request, invalid request body.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Role was not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '412':
          description: One or more user roles used were not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '423':
          description: Cannot update a read-only role.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal server error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - iam:roles:write
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutRolesByIdRequest'
        required: true
  /iam/roles/{id}/users:
    get:
      description: Retrieves all user accounts that have been assigned the specified user role.
      summary: listUsersByRole
      tags:
      - roles
      operationId: listUsersByRole
      deprecated: false
      parameters:
      - name: id
        in: path
        required: true
        description: role id
        schema:
          type: string
      - name: offset
        in: query
        required: false
        description: The offset to be used for the resulting user account list.
        schema:
          type: integer
          format: int32
          default: 0
          maximum: 1000000.0
          minimum: 0.0
      - name: count
        in: query
        required: false
        description: The number of requested user accounts.
        schema:
          type: integer
          format: int32
          default: 25
          maximum: 50.0
      responses:
        default:
          description: Default response
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '200':
          description: Returns all users by role.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/GetUsersByRoleResponse'
            application/json:
              schema:
                $ref: '#/components/schemas/GetUsersByRoleResponse'
        '400':
          description: Bad Request, invalid query parameters.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '404':
          description: Role not found.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              schema:
                type: string
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal Server Error.
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '502':
          description: Bad Gateway
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
        '503':
          description: Service Unavailable
          headers: {}
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
            application/json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
      - oauth:
        - iam:roles:read
components:
  schemas:
    GetPermissionsResponse:
      title: GetPermissionsResponse
      description: Returns a list of available permissions the system provides.
      type: object
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/Permission'
    Role:
      title: Role
      description: Needed for granting permissions per group not individually.
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        id:
          description: Identifier of the role.
          type: string
        is_readonly:
          description: The role is read-only and not editable.
          type: boolean
        name:
          description: Name of the role.
          type: string
        permissions:
          description: List of permissions which are assigned to the role.
          type: array
          items:
            $ref: '#/components/schemas/Permission'
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - name
    RoleItem:
      title: RoleItem
      description: Needed for granting permissions per group not individually.
      type: object
      properties:
        id:
          description: Identifier of the role.
          type: string
        is_readonly:
          description: The role is read-only and not editable.
          type: boolean
        name:
          description: Name of the role.
          type: string
        updated_at:
          type: string
          format: date-time
      required:
      - id
      - name
    GetUsersByRoleResponse:
      title: GetUsersByRoleResponse
      description: Gets all users by role
      type: object
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/User'
    Problem:
      title: Problem
      type: object
      properties:
        detail:
          description: A human readable explanation specific to this occurrence of the problem that is helpful to locate the problem and give advice on how to proceed. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: some description for the error situation
          type: string
        error_code:
          type: string
        instance:
          description: A URI reference that identifies the specific occurrence of the problem, e.g. by adding a fragment identifier or sub-path to the problem type. May be used to locate the root of this problem in the source code.
          example: /some/uri-reference#specific-occurrence-context
          type: string
        message:
          type: string
        messages:
          type: array
          items:
            type: string
        request_id:
          type: string
        status:
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          type: integer
          minimum: 100.0
          format: int32
          exclusiveMaximum: 600.0
        title:
          description: A short summary of the problem type. Written in English and readable for engineers, usually not suited for non technical stakeholders and not localized.
          example: some title for the error situation
          type: string
        type:
          description: A URI reference that uniquely identifies the problem type only in the context of the provided API. Opposed to the specification in RFC-7807, it is neither recommended to be dereferenceable and point to a human-readable documentation nor globally unique for the problem type.
          example: /some/uri-reference
          type: string
          default: about:blank
    User:
      title: User
      type: object
      properties:
        associate_id:
          description: External identifier for the NewStore plattform. Formerly known as "newstore_id".
          type: string
        created_at:
          type: string
          format: date-time
        email:
          description: Email address of the user.
          type: string
        external_directory:
          description: User is managed by an external directory.
          type: boolean
        first_name:
          description: First name of the user.
          type: string
        id:
          description: Identifier of the user.
          type: string
        is_active:
          description: Whether the user can login or not.
          type: boolean
        last_login_at:
          description: Shows last login time of the user. If user never logged in the property is not presence.
          type: string
          format: date-time
        last_name:
          description: Last name of the user.
          type: string
        phone:
          description: Telephone number of the user.
          type: string
        roles:
          description: List of roles the user is assigned to.
          type: array
          items:
            $ref: '#/components/schemas/RoleItem'
        updated_at:
          type: string
          format: date-time
    PostRolesRequest:
      title: PostRolesRequest
      description: Needed for granting permissions per group not individually.
      type: object
      properties:
        name:
          description: Name of the role. To be valid, it can't include slashes ('/').
          type: string
          pattern: ^[^/]+$
        permissions:
          description: List of permissions.
          type: array
          items:
            $ref: '#/components/schemas/Permission'
          minItems: 1
      required:
      - name
      - permissions
    PutRolesByIdRequest:
      title: PutRolesByIdRequest
      description: Needed for granting permissions per group not individually.
      type: object
      properties:
        name:
          description: Name of the role. To be valid, it can't include slashes ('/').
          type: string
          pattern: ^[^/]+$
        permissions:
          description: List of permissions.
          type: array
          items:
            $ref: '#/components/schemas/Permission'
          minItems: 1
      required:
      - name
      - permissions
    Application:
      title: Application
      description: Abbreviation of the application this permission belongs to.
      type: string
      enum:
      - nom
      - aa
      - mcp
    Permission:
      title: Permission
      description: List of all available system permissions.
      type: object
      properties:
        application:
          type: object
          allOf:
          - $ref: '#/components/schemas/Application'
          - description: Abbreviation of the application this permission belongs to.
        children:
          description: Nested list of child permissions.
          type: array
          items:
            $ref: '#/components/schemas/Permission'
          minItems: 1
        name:
          description: Name of the permission.
          type: string
      required:
      - application
      - name
    GetRolesResponse:
      title: GetRolesResponse
      description: Returns a list of roles.


# --- truncated at 32 KB (34 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/newstore/refs/heads/main/openapi/newstore-roles-api-openapi.yml