Navigation

Create a Configuration for a Third-Party Service Integration

Info With Circle IconCreated with Sketch.Note

Groups and projects are synonymous terms. Your {GROUP-ID} is the same as your project ID. For existing groups, your group/project ID remains the same. The resource and corresponding endpoints use the term groups.

Important With Circle IconCreated with Sketch.Important

Each project can only have one configuration per {INTEGRATION-TYPE}.

https://cloud.mongodb.com/api/atlas/v1.0

POST /api/atlas/v1.0/groups/{GROUP-ID}/integrations/{INTEGRATION-TYPE}
ParameterRequired/OptionalDescription
{GROUP-ID}RequiredProject identifier.
{INTEGRATION-TYPE}Required

Third-party service identifier. Accepted values are:

  • PAGER_DUTY
  • SLACK
  • DATADOG
  • NEW_RELIC
  • OPS_GENIE
  • VICTOR_OPS
  • FLOWDOCK
  • WEBHOOK

The following query parameters are optional:

NameTypeNecessityDescriptionDefault
pageNumintegerOptionalPage number, starting with one, that Atlas returns of the total number of objects.1
itemsPerPageintegerOptionalNumber of items that Atlas returns per page, up to a maximum of 500.100
includeCountbooleanOptionalFlag that indicates whether Atlas returns the totalCount parameter in the response body.true
prettybooleanOptionalFlag that indicates whether Atlas returns the JSON response in the prettyprint format.false
envelopebooleanOptional

Flag that indicates whether Atlas wraps the response in an envelope.

Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query.

Endpoints that return a list of results use the results object as an envelope. Atlas adds the status parameter to the response body.

false

The request body should be a single integration view (i.e. a JSON configuration object) for a single third-party service to add to the project. Always include a type property equal to the third-party service INTEGRATION_TYPE.

ServiceConfiguration Options
PagerDuty

You must provide the following fields when you configure a PagerDuty integration:

PropertyDescription
typePAGER_DUTY
serviceKeyYour Service Key.
Slack
Important With Circle IconCreated with Sketch.Important
Slack integrations now use the OAuth2 verification method and must be initially configured, or updated from a legacy integration, through the Atlas third-party service integrations page.

Legacy tokens will soon no longer be supported.

You must provide the following fields when you reconfigure an existing Slack integration:

PropertyDescription
typeSLACK
apiTokenYour API Token.
teamNameYour team name.

You may also include the following fields:

PropertyDescription
channelNameThe channel name to reconfigure.
Datadog

You must provide the following fields when you configure a Datadog integration:

PropertyDescription
typeDATADOG
apiKeyYour API Key.
regionIndicates which API URL to use, either US or EU. Datadog will use US by default.
New Relic

You must provide the following fields when you configure a New Relic integration:

PropertyDescription
typeNEW_RELIC
licenseKeyYour License Key.
accountIdUnique identifier of your New Relic account.
writeTokenYour Insights Insert Key.
readTokenYour Insights Query Key.
Opsgenie

You must provide the following fields when you configure a Opsgenie integration:

PropertyDescription
typeOPS_GENIE
apiKeyYour API Key.
regionIndicates which API URL to use, either US or EU. Opsgenie will use US by default.
VictorOps

You must provide the following fields when you configure a VictorOps integration:

PropertyDescription
typeVICTOR_OPS
apiKeyYour API Key.

You may also include the following fields:

PropertyDescription
routingKeyAn optional field for your Routing Key.
Flowdock

You must provide the following fields when you configure a VictorOps integration:

PropertyDescription
typeFLOWDOCK
flowNameYour Flowdock Flow name.
apiTokenYour API Token.
orgNameYour Flowdock organization name.
Webhook Settings

You must provide the following fields when you configure webhook settings:

PropertyDescription
typeWEBHOOK
urlYour webhook URL.

You may also include the following fields:

PropertyDescription
secretAn optional field for your webhook secret.

The response includes a results array which lists all third-party integration configurations for the project as objects, and a totalCount of the services integrated with the project. The results array includes the integration view added by the request.

Each third-party integration configuration object includes a type property equal to its own integration type (e.g. "type": "PAGER_DUTY" for the PagerDuty service). Additionally, each third-party service configuration object provides details specific to that service. The following lists the properties returned for each third-party service configuration object:

ServiceResult
PagerDuty

A returned PagerDuty integration configuration object will contain the following fields:

PropertyDescription
typePAGER_DUTY
serviceKeyYour Service Key.
Slack

A returned Slack integration configuration object will contain the following fields:

PropertyDescription
typeSLACK
apiTokenYour API Token.
teamNameYour team name. This field may not be present with a legacy Slack integration.
channelNameThe configured Slack channel name. An empty string if the value is not set.
Datadog

A returned Datadog integration configuration object will contain the following fields:

PropertyDescription
typeDATADOG
apiKeyYour API Key.
regionIndicates which API URL is used, either US or EU. Datadog will use US by default.
New Relic

A returned New Relic integration configuration object will contain the following fields:

PropertyDescription
typeNEW_RELIC
licenseKeyYour License Key.
accountIdUnique identifier of your New Relic account.
writeTokenYour Insights Insert Key.
readTokenYour Insights Query Key.
Opsgenie

A returned Opsgenie integration configuration object will contain the following fields:

PropertyDescription
typeOPS_GENIE
apiKeyYour API Key.
regionIndicates which API URL is used, either US or EU. Opsgenie will use US by default.
VictorOps

A returned VictorOps integration configuration object will contain the following fields:

PropertyDescription
typeVICTOR_OPS
apiKeyYour API Key.

The configuration object may also contain the following fields, depending on your configuration:

PropertyDescription
routingKeyAn optional field returned if you have a Routing Key configured.
Flowdock

A returned Flowdock integration configuration object will contain the following fields:

PropertyDescription
typeFLOWDOCK
flowNameYour Flowdock Flow name.
apiTokenYour API Token.
orgNameYour Flowdock organization name.
Webhook Settings

A returned webhook configuration object will contain the following fields:

PropertyDescription
typeWEBHOOK
urlYour webhook URL.

The configuration object may also contain the following fields, depending on your configuration:

PropertyDescription
secretAn optional field returned if your webhook is configured with a secret.
curl -X POST -u "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest "https://cloud.mongodb.com/api/atlas/v1.0/groups/5d791c84ff7a2522cc4f9aa1/integrations/FLOWDOCK" \
-H 'Content-Type: application/json' \
-d '{ "type": "FLOWDOCK", "flowName": "myFlowName", "apiToken": "112233", "orgName": "myOrg" }'
{
"links": [
{
"href": "https://cloud.mongodb.com/api/atlas/v1.0/groups/5d791c84ff7a2522cc4f9aa1/integrations/FLOWDOCK?pageNum=1&itemsPerPage=100",
"rel": "self"
}
],
"results": [
{
"apiKey": "112233",
"region": "US",
"type": "DATADOG"
},
{
"apiToken": "112233",
"channelName": "My Channel",
"teamName": "My Team",
"type": "SLACK"
},
{
"apiToken": "112233",
"flowName": "myFlowName",
"orgName": "myOrg",
"type": "FLOWDOCK"
}
],
"totalCount": 3
}
Give Feedback