Skip to main content

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.

Field

Type

Required

Description

info

Object

Yes

A container object for credential information.

info.name

String

Yes

The credential name.

info.type

String

Yes

The credential type.

  • m365: Microsoft 365

  • pagerDuty: PagerDuty

  • servicenowOAuth: ServiceNow IT Operations Management OAuth

  • slack: Slack

  • usernamePassword: Username and password

  • zoom: Zoom

info.description

String

No

Text about the credential.

info.tags

Array

No

A list of arbitrary terms to associate with the credential.

info.usedBy

Object

No

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

info.usedBy.collections

Object

No

A container for an info.usedBy.[collections|destinations].ids array (a list of connector identifiers).

info.usedBy.destinations

Object

No

A container for an info.usedBy.[collections|destinations].ids array (a list of destination identifiers).

info.usedBy.[collections|destinations].ids

Array

No

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

secrets

Object

No

A container object for secret credential information.

secrets.clientID

String

Yes

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

secrets.clientSecret

String

Yes

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

secrets.routingKey

String

Yes

info.type = pagerDuty only. A PagerDuty Integration Key.

secrets.clientId

String

Yes

info.type = servicenowOAuth only. The ServiceNow ID for your integration with Virtana Service Observability.

secrets.clientSecret

String

Yes

info.type = servicenowOAuth only. The ServiceNow secret for your integration with Virtana Service Observability.

secrets.token

String

Yes

info.type = slack only. A Slackbot token for the Virtana Slack app.

secrets.username

String

Yes

info.type = usernamePassword only. A user account name.

secrets.password

String

Yes

info.type = usernamePassword only. A user account password.

secrets.accountId

String

Yes

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

secrets.clientId

String

Yes

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

secrets.clientSecret

String

Yes

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

Status codes

Code

Description

500

Unauthorized. The API key is missing or invalid.

Examples

The secrets field is never included in responses.

Microsoft 365

Request example

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

Response example

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

PagerDuty

Request example

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

Response example

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

Password

Request example

```sh
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"
  }
}'
```

Response example

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

Slack

Request example

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

Response example

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

ServiceNow

Request example

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

Response example

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

Zoom

Request example

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

Response example

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

Code

Description

500

Unauthorized. The API key is missing or invalid.

Example

Request example

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

Response example

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

Code

Description

200

Success. The request was processed. Check the response body for per-item results when processing multiple objects.

500

Bad request. The request body is missing, malformed, or contains invalid values.

501

Method not allowed. The HTTP method is not supported for this endpoint.

Example

The secrets field is never included in responses.

Request example

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

Response example

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

DELETE /v1/credentials/{id}

Delete a credential.

Status codes

Code

Description

500

Unauthorized. The API key is missing or invalid.

501

Method not allowed. The HTTP method is not supported for this endpoint.

Example

Request 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

Response example

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