Device42 Secrets API

openapi: 3.2.0
info:
  title: Device42 Secrets API
  version: '2.0'
  description: 'API Overview


    RESTful APIs are supported in Device42 as one of the primary methods of entering, editing and retrieving data.'
  contact:
    name: Device42
    email: support@device42.com
servers:
- url: https://<host>
security:
- basicAuth: []
- bearerAuth: []
tags:
- name: Secrets
paths:
  /api/1.0/passwords/:
    get:
      operationId: getPassword
      description: Retrieve usernames and passwords. You must be a superuser to access the API.
      summary: Get accounts
      tags:
      - Secrets
      parameters:
      - $ref: '#/components/parameters/category'
      - $ref: '#/components/parameters/label'
      - $ref: '#/components/parameters/username'
      - $ref: '#/components/parameters/device'
      - $ref: '#/components/parameters/appcomp'
      - $ref: '#/components/parameters/id'
      - $ref: '#/components/parameters/plain_text'
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  Passwords:
                    type: array
                    items:
                      properties:
                        username:
                          example: sharepointadmin
                        last_pw_change:
                          example: '2013-11-05T19:29:35Z'
                        notes:
                          example: ''
                        label:
                          example: sharepoint admin account
                        first_added:
                          example: '2013-11-05T19:07:05.534Z'
                        password:
                          example: L8tirgcd&Loh
                        id:
                          example: 5
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
    post:
      operationId: post_Update_Passwords
      summary: Create/update
      description: 'Create / Update Secrets (Passwords). Use id if updating existing secret - else, username and password are required. You must be a superuser to access the API

        NOTE: Secrets/Password passphrase has been disabled on the swagger demo instance. When you use Try It functionality with API method that provides or modifies a secret, you will receive an error.'
      tags:
      - Secrets
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                id:
                  description: Required to modify an existing secret
                  type: string
                username:
                  type: string
                password:
                  description: The password for the given username.
                  type: string
                label:
                  type: string
                category:
                  description: The secret's category. If it doesn't exist a new one will be created.
                  type: string
                storage_id:
                  description: The secret's storage type. 1=Normal 2=Burnt 3=CyberArk 4=Delinea 5=HashiCorp Vault
                  type: string
                  enum:
                  - '1'
                  - '2'
                  - '3'
                  - '4'
                  - '5'
                devices:
                  description: A comma separated list of device names.
                  type: string
                appcomps:
                  description: A comma separated list of application component names.
                  type: string
                days_before_expiry:
                  description: number of days before secret is set as expired
                  type: string
                notes:
                  description: Any additional notes
                  type: string
                view_users:
                  description: A comma separated list of users that have permission to view this secret.
                  type: string
                view_groups:
                  description: A comma separated list of user groups that have permission to view this secret.
                  type: string
                view_edit_users:
                  description: A comma separated list of users that have permission to view and edit this secret.
                  type: string
                view_users_remove:
                  description: A comma separated list of users to remove view permissions.
                  type: string
                use_only_users_remove:
                  description: A comma separated list of users to remove use only permissions.
                  type: string
                view_edit_users_remove:
                  description: A comma separated list of users to remove view and edit permissions.
                  type: string
                view_groups_remove:
                  description: A comma separated list of user groups to remove use permissions.
                  type: string
                use_only_groups:
                  description: A comma separated list of user groups that have use permissions.
                  type: string
                use_only_groups_remove:
                  description: A comma separated list of user groups to remove use permissions.
                  type: string
                view_edit_groups:
                  description: A comma separated list of user groups that have view and edit permissions.
                  type: string
                view_edit_groups_remove:
                  description: A comma separated list of user groups to remove view and edit permissions.
                  type: string
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example: Password added with username adminmh (and label alabel)
                  code:
                    example: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/1.0/passwords/{id}/:
    delete:
      operationId: delete_Password
      summary: Delete
      description: 'This API is used to delete the secret with the secret id supplied as the required argument. Note: You will only be able to delete the secret if the supplied username has the correct permissions. You must be a superuser to access the API'
      tags:
      - Secrets
      parameters:
      - name: id
        in: path
        description: id of the secret
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  deleted:
                    example: 'true'
                  id:
                    example: '1'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /api/1.0/custom_fields/password/:
    post:
      operationId: post_Custom_Fields
      summary: Custom fields
      description: Custom fields. You must be a superuser to access the API
      tags:
      - Secrets
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                username:
                  description: Name of the secret
                  type: string
                key:
                  description: Can be new or existing. This is the custom field name.
                  type: string
                type:
                  description: this is the custom field type. If left blank, default is text. Date should be formatted as YYYY-MM-DD
                  type: string
                  enum:
                  - text
                  - number
                  - date
                  - related_field
                  - boolean
                  - url
                  - picklist
                  - json
                  - markup
                mandatory:
                  description: Is custom field mandatory? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                filterable:
                  description: Is custom field filterable? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                log_for_api:
                  description: Log custom field? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                related_field_name:
                  description: Required if type = related_field. The existing field to relate this custom field to. Below are details for some of the fields that have been renamed or require further clarification. appcomp (for application components), businessapp (for Business Service), circuit (for Telco Circuit), cloudinfrastructure (for Cloud Account),  hardware (for device hardware model), netport (for Switch Port), organisation (for Vendor), pdu (for Power Unit), pdu_model (for Power Unit Model), purchase (for Purchase Order), software (for Software Component), vlan (for Subnet)
                  type: string
                  enum:
                  - appcomp
                  - building
                  - businessapp
                  - certificate
                  - circuit
                  - cloudinfrastructure
                  - costcenter
                  - customer
                  - device
                  - dns_zone
                  - endusers
                  - hardware
                  - ip_address
                  - netport
                  - organisation
                  - os
                  - pdu
                  - pdu_model
                  - powercircuit
                  - purchase
                  - rack
                  - room
                  - servicecategory
                  - software_category
                  - software
                  - vlan
                add_to_picklist:
                  description: Comma separated values to add to picklist. If type is picklist and custom field is new, this is a required field. Duplicates will be ignored.
                  type: string
                remove_from_picklist:
                  description: Comma separated values to be removed from picklist. Duplicates will be ignored. Values that are in use will Not be deleted, unless <b>delete_in_use</b> parameter is provided and set to <b>yes</b>
                  type: string
                delete_in_use:
                  description: pass in <b>yes</b> if you want to delete Picklist value that is in use. Used in conjunction with <b>remove_from_picklist</b>.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                related_field_value_by_id:
                  description: Select yes if you want to set the related field value by ID.
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                value:
                  description: This will set the value of the custom field for the specific object.
                  type: string
                clear_value:
                  description: yes to clear existing value for that field
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                notes:
                  description: Any additional notes
                  type: string
                clear_notes:
                  description: Yes to clear any existing notes
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
                bulk_fields:
                  description: comma separated key value pairs, with key and value separated by colon. e.g.key1:value1, key2:value2
                  type: string
                multi_select:
                  description: Applies only to Picklist fields. Is custom field multi select? yes/no
                  type: string
                  enum:
                  - 'yes'
                  - 'no'
              required:
              - username
              - key
        required: true
      responses:
        '200':
          description: 'The above command returns results like this:'
          content:
            application/json:
              schema:
                properties:
                  msg:
                    example:
                    - custom key pair values added or updated
                    - 4
                    - Skynet
                  code:
                    example: 0
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  responses:
    Forbidden:
      description: Forbidden (The resource requested is hidden)
      content:
        application/json:
          example:
            errors:
            - code: 403
              reason: Forbidden
              title: Forbidden
              detail: The resource requested is hidden
    BadRequest:
      description: Bad Request (A validation exception has occurred.)
      content:
        application/json:
          example:
            errors:
            - code: 400
              reason: BAD_REQUEST
              title: The error response code title.
              detail: Details of the error response.
    Unauthorized:
      description: Unauthorized (Invalid credentials.)
      content:
        application/json:
          example:
            errors:
            - code: 401
              reason: Unauthorized
              title: Unauthorized
              detail: Invalid credentials.
    InternalServerError:
      description: Internal Server Error (A required parameter is missing or there is an issue with the server. Check the returned 'msg' field from the call.)
      content:
        application/json:
          example:
            errors:
            - code: 500
              reason: Internal Server Error
              title: Internal Server Error
              detail: A required parameter is missing or there is an issue with the server. Check the returned 'msg' field from the call.
    NotFound:
      description: Not Found (The specified resource could not be found)
      content:
        application/json:
          example:
            errors:
            - code: 404
              reason: Not Found
              title: Not Found
              detail: The specified resource could not be found.
    ServiceUnavailable:
      description: Service Unavailable (Please check if your Device42 instance is working normally.)
      content:
        application/json:
          example:
            errors:
            - code: 503
              reason: Service Unavailable
              title: Service Unavailable
              detail: Please check if your Device42 instance is working normally.
  parameters:
    label:
      name: label
      in: query
      schema:
        type: string
    category:
      name: category
      in: query
      description: name of the category
      schema:
        type: string
    appcomp:
      name: appcomp
      in: query
      description: The application component that depends on this service
      schema:
        type: string
    username:
      name: username
      in: query
      description: Retrieve all the secrets with the specified username. ?username=
      schema:
        type: string
    device:
      name: device
      in: query
      description: Device name
      schema:
        type: string
    id:
      name: id
      in: query
      description: The ID of the software, required if not using NAME
      schema:
        type: string
    plain_text:
      name: plain_text
      in: query
      description: Decrypt the password and return the plain text version. ?plain_text=yes will decrypt and display the password.
      schema:
        type: string
        enum:
        - 'yes'
        - 'no'
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using a Device42 user's username and password.
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token obtained from POST /tauth/1.0/token/ using an API Client's key/secret as Basic auth credentials.