action.skip

Credentials management service

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

Resource list

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.
apiKey (string, required)
(type = zoom only) The API key of your Zoom JWT app.
apiSecret (string, required)
(type = zoom only) The API secret of your Zoom JWT app.

Status codes

  • 500 (missing or invalid authentication key)

Examples

The secrets field is never included in responses.

Microsoft 365

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

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

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

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

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

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": {
    "apiKey": "YOUR-API-KEY",
    "apiSecret": "YOUR-API-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

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. 

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

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"
}