Credentials management service

The credentials management service provides resources for managing the credentials that are required to integrate with external services.

Resource list

• Create a credential (POST /v1/credentials/)
• Get all credentials (GET /v1/credentials)
• Update a credential (PUT /v1/credentials/{id})
• Delete a credential (DELETE /v1/credentials/{id})

POST /v1/credentials

Create a credential.

Request template

An abstract preview of a JSON request to create one credential.

{
  "info": {
    "name": "<name>",
    "type": "<type>",
    "description": "<description>",
    "tags": [ "<tag>" ]
  },
  "secrets": {
    "<key>": "<value>",
    "<key>": "<value>"
  }
}

Request fields

Create requests must include an info field and may include a secrets field. The contents of a secrets field vary by credential type. The allowedApiClients field is reserved for future use.

info (object, required)

A container object for credential information.

name (string, required)

The credential name.

type (string, required)

The credential type.

• m365 — Microsoft 365
• pagerDuty — PagerDuty
• servicenowOAuth — ServiceNow IT Operations Management OAuth
• slack — Slack
• usernamePassword — Username and password
• zoom — Zoom

description (string, optional)

Text about the credential.

tags (array, optional)

A list of arbitrary terms to associate with the credential.

usedBy (object, optional)

A container for collections and destinations objects (either or both).

collections (object, optional)

A container for an ids array (a list of connector identifiers).

destinations (object, optional)

A container for an ids array (a list of destination identifiers).

ids (array, optional)

A list of connector or destination identifiers that use the credential.

secrets (object, optional)

A container object for secret credential information.

clientID (string, required)

(type = m365 only) The client ID from the Essentials area on the home page of your Microsoft 365 app registration.

clientSecret (string, required)

(type = m365 only) The client secret from the Certificates & secrets page of your Microsoft 365 app registration.

routingKey (string, required)

(type = pagerDuty only) A PagerDuty Integration Key.

clientId (string, required)

(type = servicenowOAuth only) The ServiceNow ID for your integration with Zenoss Cloud.

clientSecret (string, required)

(type = servicenowOAuth only) The ServiceNow secret for your integration with Zenoss Cloud.

token (string, required)

(type = slack only) A Slack bot token for the Zenoss Slack app.

username (string, required)

(type = usernamePassword only) A user account name.

password (string, required)

(type = usernamePassword only) A user account password.

accountId (string, required)

(type = zoom only) The account ID of your Zoom OAuth app.

clientId (string, required)

(type = zoom only) The client ID of your Zoom OAuth app.

clientSecret (string, required)

(type = zoom only) The client secret of your Zoom OAuth app.

Status codes

• 500 (missing or invalid authentication key)

Examples

The secrets field is never included in responses.

Microsoft 365

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/credentials \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -d \
'{
  "info": {
    "name": "marketing-teams",
    "type": "m365",
    "description": "Marketing - Teams",
    "tags": [
      "marketing"
    ]
  },
  "secrets": {
    "clientId": "YOUR-CLIENT-ID",
    "clientSecret": "YOUR-CLIENT-SECRET"
  }
}'

{
  "info": {
    "id": "5235aff4-0923-5938-1f9e-eeb3753fe5a3",
    "info": {
      "name": "marketing-teams",
      "type": "m365",
      "description": "Marketing - Teams",
      "tags": [
        "marketing"
      ],
      "usedBy": {},
      "allowedApiClients": []
    }
  }
}

PagerDuty

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/credentials \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -d \
'{
  "info": {
    "name": "marketing-pagerduty",
    "type": "pagerDuty",
    "description": "Marketing - PagerDuty",
    "tags": [
      "marketing"
    ]
  },
  "secrets": {
    "routingKey": "YOUR-ROUTING-KEY"
  }
}'

{
  "info": {
    "id": "d29453c4-ef8e-324e-4cb6-0d6fd4023feb",
    "info": {
      "name": "marketing-pagerduty",
      "type": "pagerDuty",
      "description": "Marketing - PagerDuty",
      "tags": [
        "marketing"
      ],
      "usedBy": {},
      "allowedApiClients": []
    }
  }
}

Password

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/credentials \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -d \
'{
  "info": {
    "name": "marketing-password",
    "type": "usernamePassword",
    "description": "Marketing - Password",
    "tags": [
      "marketing"
    ]
  },
  "secrets": {
    "username": "craftyuser",
    "password": "CraftyIsAsCraftyDoes123"
  }
}'

{
  "info": {
    "id": "c88c8e22-23db-ab83-3404-dc9233192009",
    "info": {
      "name": "marketing-password",
      "type": "usernamePassword",
      "description": "Marketing - Password",
      "tags": [
        "marketing"
      ],
      "usedBy": {},
      "allowedApiClients": []
    }
  }
}

Slack

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/credentials \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -d \
'{
  "info": {
    "name": "marketing-slack",
    "type": "slack",
    "description": "Marketing - Slack",
    "tags": [
      "marketing"
    ]
  },
  "secrets": {
    "token": "YOUR-JWT-TOKEN"
  }
}'

{
  "info": {
    "id": "0eae9bd7-2106-c67b-a053-5e574f4f8743",
    "info": {
      "name": "marketing-slack",
      "type": "slack",
      "description": "Marketing - Slack",
      "tags": [
        "marketing"
      ],
      "usedBy": {},
      "allowedApiClients": []
    }
  }
}

ServiceNow

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/credentials \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -d \
'{
  "info": {
    "name": "marketing-servicenow",
    "type": "servicenowOAuth",
    "description": "Marketing - ServiceNow",
    "tags": [
      "marketing"
    ]
  },
  "secrets": {
    "clientId": "YOUR-CLIENT-ID",
    "clientSecret": "YOUR-CLIENT-SECRET"
  }
}'

{
  "info": {
    "id": "c3c36b07-f301-bfa9-9e2e-aa1ba43343e8",
    "info": {
      "name": "marketing-servicenow",
      "type": "servicenowOAuth",
      "description": "Marketing - ServiceNow",
      "tags": [
        "marketing"
      ],
      "usedBy": {},
      "allowedApiClients": []
    }
  }
}

Zoom

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/credentials \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X POST -s -d \
{
  "info": {
    "name": "marketing-zoom",
    "type": "zoom",
    "description": "Marketing - Zoom",
    "tags": [
      "marketing"
    ]
  },
  "secrets": {
    "accountId": "YOUR-ACCOUNT-ID",
    "clientId": "YOUR-CLIENT-ID",
    "clientSecret": "YOUR-CLIENT-SECRET"
  }
}

{
  "info": {
    "id": "5e63e8c0-992f-ed53-a2da-ff1f8307f272",
    "info": {
      "name": "marketing-zoom",
      "type": "zoom",
      "description": "Marketing - Zoom",
      "tags": [
        "marketing"
      ],
      "usedBy": {},
      "allowedApiClients": []
    }
  }
}

GET /v1/credentials

Get all credentials.

Status codes

• 500 (missing or invalid authentication key)

Example

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/credentials \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X GET -s

{
  "credentials": [
    {
      "id": "db98013d-41d8-7b3a-a9f1-2c4e37873594",
      "info": {
        "name": "mkt-teams",
        "type": "m365",
        "description": "Marketing - Teams",
        "tags": [
          "marketing"
        ],
        "usedBy": {},
        "allowedApiClients": []
      }
    },
    {
      "id": "fb0e160d-fd51-9349-14f0-83ae56723a9a",
      "info": {
        "name": "mkt-zoom",
        "type": "zoom",
        "description": "Marketing - Zoom",
        "tags": [
          "marketing"
        ],
        "usedBy": {},
        "allowedApiClients": []
      }
    }
  ],
  "nextPageToken": "",
  "totalCount": "2"
}

PUT /v1/credentials/{id}

Update a credential.

Request fields

Update requests use the same fields as create requests.

Note

If you include both an info field and a secrets field in an update request, their contents completely replace the credential's record on the server. However, if you do not include a secrets field in an update request, the existing secrets field (if any) is unchanged.

Status codes

• 200 (success)
• 500 (missing or invalid authentication key)
• 501 (method not allowed)

Example

The secrets field is never included in responses.

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/credentials/YOUR-CREDENTIAL-ID \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X PUT -s -d \
{
  "info": {
    "name": "marketing-zoom-updated",
    "type": "zoom",
    "description": "Marketing - Zoom (updated)",
    "tags": [
      "marketing"
    ]
  },
  "secrets": {
    "apiKey": "YOUR-API-KEY",
    "apiSecret": "YOUR-API-SECRET"
  }
}

{
  "info": {
    "name": "marketing-zoom-updated",
    "type": "zoom",
    "description": "Marketing - Zoom (updated)",
    "tags": [
      "marketing"
    ],
    "usedBy": {},
    "allowedApiClients": []
  }
}

DELETE /v1/credentials/{id}

Delete a credential.

Status codes

• 500 (missing or invalid authentication key)
• 501 (method not allowed)

Example

RequestResponse

curl https://YOUR-API-ENDPOINT/v1/credentials/YOUR-CREDENTIAL-ID \
  -H "content-type: application/json" \
  -H "zenoss-api-key: YOUR-API-KEY" \
  -X DELETE -s 

{
  "id": "db98013d-41d8-7b3a-a9f1-2c4e37873594"
}