Skip to content
adversarial

Save a connection and its capability configurations atomically

POST
/v1/integrations/{provider}/save
curl --request POST \
  --url https://api.adversarial.com/api/v1/integrations/example/save \
  --header 'Content-Type: application/json' \
  --data '{ "configs": [ { "capability": "RISK_REGISTER", "config": {}, "config_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "display_name": "example", "enabled": true } ], "installation": { "auth_method": null, "connection": {}, "credentials": {}, "display_name": null }, "installation_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" }'

Creates an installation when its identifier is omitted. Existing configurations are replaced by identifier; unlisted configurations remain. If any validation or write fails, none of the requested changes persist.

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
provider
required
string

Provider slug

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Save a connection and its capability configurations atomically.

object
configs

Configurations to create or replace. Unlisted configurations are retained.

Array<object>

One complete capability configuration in an atomic save.

object
capability
required

Capability selected from the provider catalog. Must match an existing configuration.

string
Allowed values: RISK_REGISTER INCIDENT_REGISTER RISK_TICKET INCIDENT_TICKET NOTIFICATION
config

Complete configuration value. Omitted means an empty configuration.

object
config_id

Existing configuration to replace. Omit to create a configuration.

string | null format: uuid
display_name
required

Configuration name, unique within this installation and capability.

string
enabled
required

Whether this configuration can execute.

boolean
installation
One of:

Connection changes. Creation requires name, authentication method, connection values, and credentials. Omit for a configuration-only save.

object
auth_method
One of:

Replacement authentication method. Supply credentials in the same request.

string
Allowed values: api_key basic bearer oauth2_client_credentials
connection

Replacement non-secret connection values.

object
credentials

Complete write-only credential replacement.

object
display_name

Replacement installation name.

string | null
installation_id

Existing installation to update. Omit to create an installation.

string | null format: uuid

Responses

Section titled “Responses”

200

Section titled “200”

Saved installation with all capability configurations

Media typeapplication/json

One installed provider connection.

object
auth_error

Safe authentication error, cleared after successful recovery.

string | null
auth_failed_at

Time of the most recent authentication failure.

string | null format: date-time
auth_failure_count
required

Sequential authentication failures since the last accepted provider request.

integer format: int32
auth_method
required

Selected authentication method.

string
Allowed values: api_key basic bearer oauth2_client_credentials
configs
required

Capability configurations owned by this installation.

Array<object>

One capability configuration under an installation.

object
capability
required

Capability identifier.

string
Allowed values: RISK_REGISTER INCIDENT_REGISTER RISK_TICKET INCIDENT_TICKET NOTIFICATION
config
required

Complete validated configuration value.

object
created_date
required

Creation time.

string format: date-time
display_name
required

Name that tells sibling configurations of one capability apart under one installation.

string
enabled
required

Whether the platform can execute this configuration.

boolean
id
required

Configuration identifier.

string format: uuid
installation_id
required

Installation whose credential this configuration runs with.

string format: uuid
updated_date
required

Last update time.

string format: date-time
connection
required

Non-secret connection values.

object
created_date
required

Creation time.

string format: date-time
credentials_set
required

Whether encrypted credentials are present.

boolean
display_name
required

Operator-chosen installation name, unique per organization and provider.

string
id
required

Installation identifier.

string format: uuid
integration_user
required

Service account the platform acts as for this installation.

string format: uuid
provider
required

Canonical provider identifier.

string
status
required

Current lifecycle status.

string
updated_date
required

Last update time.

string format: date-time
Example
{
  "auth_method": "api_key",
  "configs": [
    {
      "capability": "RISK_REGISTER"
    }
  ]
}

400

Section titled “400”

Invalid connection or capability configuration

404

Section titled “404”

Unknown provider, installation, or configuration

409

Section titled “409”

Concurrent change or a name already in use