openapi: 3.1.0
info:
  title: Demandbase Admin API
  description: >-
    Provides programmatic access to user management and platform administration
    capabilities, including creating, reading, updating, and deleting users
    and managing API key sets for Demandbase One.
  version: '1.0'
  contact:
    name: Demandbase Support
    url: https://support.demandbase.com/
  termsOfService: https://www.demandbase.com/terms-of-service/
externalDocs:
  description: Demandbase Admin API Documentation
  url: https://support.demandbase.com/hc/en-us/sections/360011444531-API-Documentation
servers:
  - url: https://api.demandbase.com
    description: Demandbase Admin API Production
tags:
  - name: API Keys
    description: API key set management
  - name: Roles
    description: Role and permission management
  - name: Users
    description: User management operations
security:
  - bearerAuth: []
paths:
  /admin/v1/users:
    get:
      operationId: listUsers
      summary: Demandbase List users
      description: >-
        Retrieve a list of all users in the Demandbase One organization
        with their roles and status.
      tags:
        - Users
      parameters:
        - name: status
          in: query
          required: false
          description: Filter by user status
          schema:
            type: string
            enum:
              - active
              - inactive
              - pending
        - name: role
          in: query
          required: false
          description: Filter by user role
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 25
            maximum: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: object
                properties:
                  users:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  total:
                    type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - insufficient permissions
    post:
      operationId: createUser
      summary: Demandbase Create a user
      description: Create a new user in the Demandbase One organization.
      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 request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '409':
          description: User with email already exists
  /admin/v1/users/{userId}:
    get:
      operationId: getUser
      summary: Demandbase Get a user
      description: Retrieve details of a specific user.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/userId'
      responses:
        '200':
          description: User details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: User not found
    put:
      operationId: updateUser
      summary: Demandbase Update a user
      description: Update an existing user's details and role assignments.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/userId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: User not found
    delete:
      operationId: deleteUser
      summary: Demandbase Delete a user
      description: Delete a user from the Demandbase One organization.
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/userId'
      responses:
        '204':
          description: User deleted
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: User not found
  /admin/v1/api-keys:
    get:
      operationId: listApiKeys
      summary: Demandbase List API key sets
      description: Retrieve all API key sets for the organization.
      tags:
        - API Keys
      responses:
        '200':
          description: List of API key sets
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_keys:
                    type: array
                    items:
                      $ref: '#/components/schemas/ApiKeySet'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
    post:
      operationId: createApiKey
      summary: Demandbase Create an API key set
      description: >-
        Generate a new API key set for programmatic access to Demandbase APIs.
      tags:
        - API Keys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
      responses:
        '201':
          description: API key set created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeySet'
        '400':
          description: Invalid request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
  /admin/v1/api-keys/{keyId}:
    get:
      operationId: getApiKey
      summary: Demandbase Get an API key set
      description: Retrieve details of a specific API key set.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/keyId'
      responses:
        '200':
          description: API key set details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeySet'
        '401':
          description: Unauthorized
        '404':
          description: API key set not found
    delete:
      operationId: deleteApiKey
      summary: Demandbase Delete an API key set
      description: Revoke and delete an API key set.
      tags:
        - API Keys
      parameters:
        - $ref: '#/components/parameters/keyId'
      responses:
        '204':
          description: API key set deleted
        '401':
          description: Unauthorized
        '404':
          description: API key set not found
  /admin/v1/roles:
    get:
      operationId: listRoles
      summary: Demandbase List roles
      description: Retrieve all available roles and their permissions.
      tags:
        - Roles
      responses:
        '200':
          description: List of roles
          content:
            application/json:
              schema:
                type: object
                properties:
                  roles:
                    type: array
                    items:
                      $ref: '#/components/schemas/Role'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer token with admin scope
  parameters:
    userId:
      name: userId
      in: path
      required: true
      description: User unique identifier
      schema:
        type: string
    keyId:
      name: keyId
      in: path
      required: true
      description: API key set unique identifier
      schema:
        type: string
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          description: User unique identifier
        email:
          type: string
          format: email
          description: User email address
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
        role:
          type: string
          description: Assigned role
        status:
          type: string
          enum:
            - active
            - inactive
            - pending
          description: User status
        last_login:
          type: string
          format: date-time
          description: Last login timestamp
        created_at:
          type: string
          format: date-time
          description: Account creation timestamp
        updated_at:
          type: string
          format: date-time
          description: Last update timestamp
    CreateUserRequest:
      type: object
      required:
        - email
        - first_name
        - last_name
        - role
      properties:
        email:
          type: string
          format: email
          description: User email address
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
        role:
          type: string
          description: Role to assign
    UpdateUserRequest:
      type: object
      properties:
        first_name:
          type: string
          description: First name
        last_name:
          type: string
          description: Last name
        role:
          type: string
          description: Role to assign
        status:
          type: string
          enum:
            - active
            - inactive
          description: User status
    ApiKeySet:
      type: object
      properties:
        id:
          type: string
          description: API key set unique identifier
        name:
          type: string
          description: API key set name
        api_key:
          type: string
          description: API key (only shown on creation)
        api_secret:
          type: string
          description: API secret (only shown on creation)
        scopes:
          type: array
          items:
            type: string
          description: Authorized API scopes
        status:
          type: string
          enum:
            - active
            - revoked
          description: Key set status
        created_at:
          type: string
          format: date-time
          description: Creation timestamp
        created_by:
          type: string
          description: User who created the key set
        last_used:
          type: string
          format: date-time
          description: Last usage timestamp
    CreateApiKeyRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Descriptive name for the API key set
        scopes:
          type: array
          items:
            type: string
          description: API scopes to authorize
    Role:
      type: object
      properties:
        id:
          type: string
          description: Role unique identifier
        name:
          type: string
          description: Role name
        description:
          type: string
          description: Role description
        permissions:
          type: array
          items:
            type: string
          description: List of permissions granted by this role