openapi: 3.1.0
info:
  title: Oracle Essbase REST Application Configuration Users API
  description: RESTful API for managing and interacting with Oracle Essbase applications, databases, and performing analytical operations. Enables automation of Essbase resource management with endpoints for applications, databases, calculations, data loads, user management, sessions, jobs, files, scripts, filters, partitions, connections, datasources, dimensions, outline viewer, locks, scenarios, server properties, and more. All communication occurs over secured HTTP.
  version: 21.0.0
  contact:
    name: Oracle Support
    url: https://support.oracle.com
  license:
    name: Oracle Technology Network License
    url: https://www.oracle.com/legal/terms/
  x-provider: oracle-essbase
servers:
- url: https://{host}:{port}/essbase/rest/v1
  description: Oracle Essbase REST API server
  variables:
    host:
      default: localhost
      description: Essbase server hostname
    port:
      default: '9001'
      description: Essbase server port
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Users
  description: Create, search, update, and delete users
paths:
  /users:
    get:
      operationId: listUsers
      summary: Oracle Essbase List Users
      description: 'Returns a list of Essbase users. Supports filtering by name pattern and limiting results. Use expand=all to include service roles and group memberships. Supports CSV export via Accept: application/octet-stream header. Not available in EPM Shared Services security mode.'
      tags:
      - Users
      parameters:
      - name: expand
        in: query
        description: Include service role and groups. Values are all or none.
        schema:
          type: string
          enum:
          - all
          - none
          default: all
      - name: filter
        in: query
        description: User ID wildcard pattern for filtering.
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of users to return. -1 for no limit.
        schema:
          type: integer
          format: int32
          default: -1
      responses:
        '200':
          description: User list returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserList'
            application/octet-stream:
              schema:
                type: string
                format: binary
                description: CSV export of users.
        '400':
          description: User may not have appropriate service role.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: createUser
      summary: Oracle Essbase Create User
      description: Creates a new Essbase user with the specified details and role assignment.
      tags:
      - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '200':
          description: User created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Failed to create user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /users/{userId}:
    get:
      operationId: getUser
      summary: Oracle Essbase Get User
      description: Returns details of the specified user including roles and group memberships.
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        description: User identifier.
        schema:
          type: string
      responses:
        '200':
          description: User details returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Bad request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      operationId: updateUser
      summary: Oracle Essbase Update User
      description: Updates details of the specified user such as email, role, or password.
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        description: User identifier.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '200':
          description: User updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Failed to update user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteUser
      summary: Oracle Essbase Delete User
      description: Deletes the specified user from Essbase.
      tags:
      - Users
      parameters:
      - name: userId
        in: path
        required: true
        description: User identifier.
        schema:
          type: string
      responses:
        '200':
          description: User deleted successfully.
        '400':
          description: Failed to delete user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    User:
      type: object
      description: An Essbase user account.
      properties:
        id:
          type: string
          description: User identifier.
        name:
          type: string
          description: User display name (max 256 characters).
          maxLength: 256
        email:
          type: string
          format: email
          description: User email address.
        password:
          type: string
          format: password
          description: User password (write-only, not returned in responses).
        role:
          type: string
          description: User service role.
          enum:
          - User
          - Power User
          - Service Administrator
        token:
          type: string
          description: User authentication token.
        groups:
          type: array
          description: List of group names the user belongs to.
          items:
            type: string
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
    UserList:
      type: object
      description: Paginated list of users.
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/User'
        totalResults:
          type: integer
          format: int64
        count:
          type: integer
          format: int64
        limit:
          type: integer
          format: int64
        offset:
          type: integer
          format: int64
        hasMore:
          type: boolean
    UserInput:
      type: object
      description: Input for creating or updating a user.
      required:
      - id
      properties:
        id:
          type: string
          description: User identifier.
        name:
          type: string
          description: User display name.
          maxLength: 256
        email:
          type: string
          format: email
          description: User email address.
        password:
          type: string
          format: password
          description: User password.
        role:
          type: string
          description: User service role.
          enum:
          - User
          - Power User
          - Service Administrator
        groups:
          type: array
          description: Group names to assign the user to.
          items:
            type: string
    Link:
      type: object
      description: HATEOAS navigation link.
      properties:
        rel:
          type: string
          description: Link relation type.
        href:
          type: string
          format: uri
          description: Link URL.
        method:
          type: string
          description: HTTP method for this link.
        type:
          type: string
          description: Media type of the linked resource.
    Error:
      type: object
      description: Error response from the Essbase REST API.
      properties:
        message:
          type: string
          description: Human-readable error message.
        errorCode:
          type: string
          description: Machine-readable error code.
        details:
          type: string
          description: Additional error details.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using Essbase username and password.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token authentication for cloud deployments on Oracle Cloud Infrastructure.