Activate project plugin configuration

Makes the configuration the project's active layer and returns the resulting effective configuration. When trusted signer keys are configured, its signature and artifacts are verified first. Requires edit_project_settings on the Guardian project, checked with Auth Service for every caller, a platform admin included; an unknown project is 403 like a forbidden one. Without the Guardian adapter the route answers 503.

posthttps://<host>/api/v1/projects/{project_uuid}/plugin-configurations/{configurationId}/activate

bash

curl --request POST \
  --url 'https://<host>/api/v1/projects/{project_uuid}/plugin-configurations/{configurationId}/activate' \
  --header 'Authorization: Bearer <token>'

javascript

const response = await fetch("https://<host>/api/v1/projects/{project_uuid}/plugin-configurations/{configurationId}/activate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>"
  }
});

const data = await response.json();

typescript

interface ProjectConfigurationResolutionResponse {
  correlation_id?: string;
  item?: Record<string, unknown>;
}

const response = await fetch("https://<host>/api/v1/projects/{project_uuid}/plugin-configurations/{configurationId}/activate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>"
  }
});
if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);

const data: ProjectConfigurationResolutionResponse = await response.json();

python

import requests

response = requests.post(
    "https://<host>/api/v1/projects/{project_uuid}/plugin-configurations/{configurationId}/activate",
    headers={
        "Authorization": "Bearer <token>",
    },
)
response.raise_for_status()
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, err := http.NewRequest(http.MethodPost, "https://<host>/api/v1/projects/{project_uuid}/plugin-configurations/{configurationId}/activate", nil)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer <token>")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	data, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(res.Status, string(data))
}

java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://<host>/api/v1/projects/{project_uuid}/plugin-configurations/{configurationId}/activate"))
            .header("Authorization", "Bearer <token>")
            .method("POST", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode() + " " + response.body());
    }
}

csharp

using System.Net.Http.Headers;

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://<host>/api/v1/projects/{project_uuid}/plugin-configurations/{configurationId}/activate");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "<token>");

using var response = await client.SendAsync(request);
Console.WriteLine($"{(int)response.StatusCode} {await response.Content.ReadAsStringAsync()}");

php

<?php

$ch = curl_init('https://<host>/api/v1/projects/{project_uuid}/plugin-configurations/{configurationId}/activate');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer <token>',
    ],
    CURLOPT_RETURNTRANSFER => true,
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
echo $status . " " . $response . PHP_EOL;

ruby

require "net/http"

uri = URI("https://<host>/api/v1/projects/{project_uuid}/plugin-configurations/{configurationId}/activate")
request = Net::HTTP::Post.new(uri)
request["Authorization"] = "Bearer <token>"

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(request)
end
puts "#{response.code} #{response.body}"

rust

// Cargo.toml dependencies: reqwest, tokio (features "full")

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let response = reqwest::Client::new()
        .post("https://<host>/api/v1/projects/{project_uuid}/plugin-configurations/{configurationId}/activate")
        .header("Authorization", "Bearer <token>")
        .send()
        .await?;

    println!("{} {}", response.status(), response.text().await?);
    Ok(())
}

Authorizations

BearerAuth · API key in header "Authorization" — Type "Bearer" followed by a space and a sign-in token: a Guardian Platform JWT, or an OIDC ID token in a standalone deployment.
ApiKeyAuth · API key in header "Authorization" — Type "Bearer" followed by a space and a Guardian Platform API key. Project-scoped routes and registration tokens check the key's scopes and project binding. Per-agent routes accept a key bound to no project that has empty scopes or full access, which acts as its holder, or a scope for what the route does: submit_agent_assessments reads an agent (its detail, configurations, state history and the files a state references, definitions, tools and operating profile, as its assessments rest on), view_agent_certifications reads its certifications, and manage_programs or review_agent_assessments attach a certification. A state's raw snapshot and findings, its audit exchanges and plugin events, and saving its operating profile take full access. A scope counts only while the key's holder still holds that permission in the key's organization, which auth-service reports as keyHeldScopes. A key never acts as an admin, so its holder's binding to the agent still decides.

Parameters

Path parameters

Name	Type	Description
`project_uuid` required	`string`	Project UUID
`configurationId` required	`string`	Configuration ID

Responses

200OK

application/json

correlation_idstring
iteminternal_controlhttp.projectConfigurationResolution
Show internal_controlhttp.projectConfigurationResolution
- effective_hooksobject
  Show properties
  Map of plugins.EffectiveHookEntry[]
  Array of plugins.EffectiveHookEntry
  artifact_sha256string
  config_jsonobject
  configuration_idstring
  enabledboolean
  granted_capabilitiesplugins.CapabilityGrantSet
  Show plugins.CapabilityGrantSet
  agent.badge.writeplugins.AgentBadgeWriteGrant
  Show plugins.AgentBadgeWriteGrant
  allowed_keysstring[]
  cid.resolveplugins.CIDResolveGrant
  Show plugins.CIDResolveGrant
  max_bytesinteger
  http.requestplugins.HTTPRequestGrant
  Show plugins.HTTPRequestGrant
  allowed_methodsstring[]
  allowed_url_prefixesstring[]
  max_inflightinteger
  max_request_bytesinteger
  max_response_bytesinteger
  timeout_msinteger
  request.body.readplugins.RequestBodyReadGrant
  Show plugins.RequestBodyReadGrant
  max_bytesinteger
  hookplugins.HookName
  One ofrequest.startproject.bootstrapproxy.preproxy.postrequest.end
  idinteger
  layerplugins.ConfigurationLayer
  One ofglobalproject
  matchplugins.MatchCriteria
  Show plugins.MatchCriteria
  agent_idplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  gateway_pathplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  methodplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  operationplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  providerplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  upstream_pathplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  order_indexinteger
  plugin_definition_idinteger
  plugin_idstring
  plugin_modeplugins.PluginMode
  One ofenforcementobservability
  plugin_versionstring
  runtimeplugins.PluginRuntime
  One ofpremadewasm
  secret_ref_pathsstring[]
  timeout_msinteger
- globalinternal_controlhttp.projectConfigurationActivationSummary
  Show internal_controlhttp.projectConfigurationActivationSummary
  activated_atstring
  activated_bystring
  activation_idinteger
  configuration_idstring
  created_atstring
  created_bystring
  entriesplugins.PluginConfigurationEntry[]
  Show properties
  Array of plugins.PluginConfigurationEntry
  artifact_sha256string
  config_jsonobject
  configuration_idstring
  enabledboolean
  granted_capabilitiesplugins.CapabilityGrantSet
  Show plugins.CapabilityGrantSet
  agent.badge.writeplugins.AgentBadgeWriteGrant
  Show plugins.AgentBadgeWriteGrant
  allowed_keysstring[]
  cid.resolveplugins.CIDResolveGrant
  Show plugins.CIDResolveGrant
  max_bytesinteger
  http.requestplugins.HTTPRequestGrant
  Show plugins.HTTPRequestGrant
  allowed_methodsstring[]
  allowed_url_prefixesstring[]
  max_inflightinteger
  max_request_bytesinteger
  max_response_bytesinteger
  timeout_msinteger
  request.body.readplugins.RequestBodyReadGrant
  Show plugins.RequestBodyReadGrant
  max_bytesinteger
  hookplugins.HookName
  One ofrequest.startproject.bootstrapproxy.preproxy.postrequest.end
  idinteger
  matchplugins.MatchCriteria
  Show plugins.MatchCriteria
  agent_idplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  gateway_pathplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  methodplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  operationplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  providerplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  upstream_pathplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  order_indexinteger
  plugin_definition_idinteger
  plugin_idstring
  plugin_modeplugins.PluginMode
  One ofenforcementobservability
  plugin_versionstring
  runtimeplugins.PluginRuntime
  One ofpremadewasm
  secret_ref_pathsstring[]
  timeout_msinteger
  entry_countinteger
  project_urnstring
  project_uuidstring
  statusplugins.ConfigurationStatus
  One ofdraftactivesuperseded
  versioninteger
- membership_satisfiedboolean
- projectinternal_controlhttp.projectConfigurationActivationSummary
  Show internal_controlhttp.projectConfigurationActivationSummary
  activated_atstring
  activated_bystring
  activation_idinteger
  configuration_idstring
  created_atstring
  created_bystring
  entriesplugins.PluginConfigurationEntry[]
  Show properties
  Array of plugins.PluginConfigurationEntry
  artifact_sha256string
  config_jsonobject
  configuration_idstring
  enabledboolean
  granted_capabilitiesplugins.CapabilityGrantSet
  Show plugins.CapabilityGrantSet
  agent.badge.writeplugins.AgentBadgeWriteGrant
  Show plugins.AgentBadgeWriteGrant
  allowed_keysstring[]
  cid.resolveplugins.CIDResolveGrant
  Show plugins.CIDResolveGrant
  max_bytesinteger
  http.requestplugins.HTTPRequestGrant
  Show plugins.HTTPRequestGrant
  allowed_methodsstring[]
  allowed_url_prefixesstring[]
  max_inflightinteger
  max_request_bytesinteger
  max_response_bytesinteger
  timeout_msinteger
  request.body.readplugins.RequestBodyReadGrant
  Show plugins.RequestBodyReadGrant
  max_bytesinteger
  hookplugins.HookName
  One ofrequest.startproject.bootstrapproxy.preproxy.postrequest.end
  idinteger
  matchplugins.MatchCriteria
  Show plugins.MatchCriteria
  agent_idplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  gateway_pathplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  methodplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  operationplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  providerplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  upstream_pathplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  order_indexinteger
  plugin_definition_idinteger
  plugin_idstring
  plugin_modeplugins.PluginMode
  One ofenforcementobservability
  plugin_versionstring
  runtimeplugins.PluginRuntime
  One ofpremadewasm
  secret_ref_pathsstring[]
  timeout_msinteger
  entry_countinteger
  project_urnstring
  project_uuidstring
  statusplugins.ConfigurationStatus
  One ofdraftactivesuperseded
  versioninteger
- project_urnstring
- project_uuidstring
- rollback_candidatesinternal_controlhttp.projectConfigurationActivationSummary[]
  Show properties
  Array of internal_controlhttp.projectConfigurationActivationSummary
  activated_atstring
  activated_bystring
  activation_idinteger
  configuration_idstring
  created_atstring
  created_bystring
  entriesplugins.PluginConfigurationEntry[]
  Show properties
  Array of plugins.PluginConfigurationEntry
  artifact_sha256string
  config_jsonobject
  configuration_idstring
  enabledboolean
  granted_capabilitiesplugins.CapabilityGrantSet
  Show plugins.CapabilityGrantSet
  agent.badge.writeplugins.AgentBadgeWriteGrant
  Show plugins.AgentBadgeWriteGrant
  allowed_keysstring[]
  cid.resolveplugins.CIDResolveGrant
  Show plugins.CIDResolveGrant
  max_bytesinteger
  http.requestplugins.HTTPRequestGrant
  Show plugins.HTTPRequestGrant
  allowed_methodsstring[]
  allowed_url_prefixesstring[]
  max_inflightinteger
  max_request_bytesinteger
  max_response_bytesinteger
  timeout_msinteger
  request.body.readplugins.RequestBodyReadGrant
  Show plugins.RequestBodyReadGrant
  max_bytesinteger
  hookplugins.HookName
  One ofrequest.startproject.bootstrapproxy.preproxy.postrequest.end
  idinteger
  matchplugins.MatchCriteria
  Show plugins.MatchCriteria
  agent_idplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  gateway_pathplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  methodplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  operationplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  providerplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  upstream_pathplugins.MatchRule
  Show plugins.MatchRule
  operatorplugins.FilterOperator
  One ofexactprefix
  valuestring
  order_indexinteger
  plugin_definition_idinteger
  plugin_idstring
  plugin_modeplugins.PluginMode
  One ofenforcementobservability
  plugin_versionstring
  runtimeplugins.PluginRuntime
  One ofpremadewasm
  secret_ref_pathsstring[]
  timeout_msinteger
  entry_countinteger
  project_urnstring
  project_uuidstring
  statusplugins.ConfigurationStatus
  One ofdraftactivesuperseded
  versioninteger
- stateplugins.ConfigurationResolutionState
  One ofactiveempty

Examplejson

{
  "correlation_id": "string",
  "item": {
    "effective_hooks": {
      "key": [
        {
          "artifact_sha256": "string",
          "config_json": {},
          "configuration_id": "string",
          "enabled": true,
          "granted_capabilities": {
            "agent.badge.write": {
              "allowed_keys": [
                "string"
              ]
            },
            "cid.resolve": {
              "max_bytes": 0
            },
            "http.request": {
              "allowed_methods": [
                "string"
              ],
              "allowed_url_prefixes": [
                "string"
              ],
              "max_inflight": 0,
              "max_request_bytes": 0,
              "max_response_bytes": 0,
              "timeout_ms": 0
            },
            "request.body.read": {
              "max_bytes": 0
            }
          },
          "hook": "request.start",
          "id": 0,
          "layer": "global",
          "match": {
            "agent_id": {
              "operator": "exact",
              "value": "string"
            },
            "gateway_path": {
              "operator": "exact",
              "value": "string"
            },
            "method": {
              "operator": "exact",
              "value": "string"
            },
            "operation": {
              "operator": "exact",
              "value": "string"
            },
            "provider": {
              "operator": "exact",
              "value": "string"
            },
            "upstream_path": {
              "operator": "exact",
              "value": "string"
            }
          },
          "order_index": 0,
          "plugin_definition_id": 0,
          "plugin_id": "string",
          "plugin_mode": "enforcement",
          "plugin_version": "string",
          "runtime": "premade",
          "secret_ref_paths": [
            "string"
          ],
          "timeout_ms": 0
        }
      ]
    },
    "global": {
      "activated_at": "string",
      "activated_by": "string",
      "activation_id": 0,
      "configuration_id": "string",
      "created_at": "string",
      "created_by": "string",
      "entries": [
        {
          "artifact_sha256": "string",
          "config_json": {},
          "configuration_id": "string",
          "enabled": true,
          "granted_capabilities": {
            "agent.badge.write": {
              "allowed_keys": [
                "string"
              ]
            },
            "cid.resolve": {
              "max_bytes": 0
            },
            "http.request": {
              "allowed_methods": [
                "string"
              ],
              "allowed_url_prefixes": [
                "string"
              ],
              "max_inflight": 0,
              "max_request_bytes": 0,
              "max_response_bytes": 0,
              "timeout_ms": 0
            },
            "request.body.read": {
              "max_bytes": 0
            }
          },
          "hook": "request.start",
          "id": 0,
          "match": {
            "agent_id": {
              "operator": "exact",
              "value": "string"
            },
            "gateway_path": {
              "operator": "exact",
              "value": "string"
            },
            "method": {
              "operator": "exact",
              "value": "string"
            },
            "operation": {
              "operator": "exact",
              "value": "string"
            },
            "provider": {
              "operator": "exact",
              "value": "string"
            },
            "upstream_path": {
              "operator": "exact",
              "value": "string"
            }
          },
          "order_index": 0,
          "plugin_definition_id": 0,
          "plugin_id": "string",
          "plugin_mode": "enforcement",
          "plugin_version": "string",
          "runtime": "premade",
          "secret_ref_paths": [
            "string"
          ],
          "timeout_ms": 0
        }
      ],
      "entry_count": 0,
      "project_urn": "string",
      "project_uuid": "string",
      "status": "draft",
      "version": 0
    },
    "membership_satisfied": true,
    "project": {
      "activated_at": "string",
      "activated_by": "string",
      "activation_id": 0,
      "configuration_id": "string",
      "created_at": "string",
      "created_by": "string",
      "entries": [
        {
          "artifact_sha256": "string",
          "config_json": {},
          "configuration_id": "string",
          "enabled": true,
          "granted_capabilities": {
            "agent.badge.write": {
              "allowed_keys": [
                "string"
              ]
            },
            "cid.resolve": {
              "max_bytes": 0
            },
            "http.request": {
              "allowed_methods": [
                "string"
              ],
              "allowed_url_prefixes": [
                "string"
              ],
              "max_inflight": 0,
              "max_request_bytes": 0,
              "max_response_bytes": 0,
              "timeout_ms": 0
            },
            "request.body.read": {
              "max_bytes": 0
            }
          },
          "hook": "request.start",
          "id": 0,
          "match": {
            "agent_id": {
              "operator": "exact",
              "value": "string"
            },
            "gateway_path": {
              "operator": "exact",
              "value": "string"
            },
            "method": {
              "operator": "exact",
              "value": "string"
            },
            "operation": {
              "operator": "exact",
              "value": "string"
            },
            "provider": {
              "operator": "exact",
              "value": "string"
            },
            "upstream_path": {
              "operator": "exact",
              "value": "string"
            }
          },
          "order_index": 0,
          "plugin_definition_id": 0,
          "plugin_id": "string",
          "plugin_mode": "enforcement",
          "plugin_version": "string",
          "runtime": "premade",
          "secret_ref_paths": [
            "string"
          ],
          "timeout_ms": 0
        }
      ],
      "entry_count": 0,
      "project_urn": "string",
      "project_uuid": "string",
      "status": "draft",
      "version": 0
    },
    "project_urn": "string",
    "project_uuid": "string",
    "rollback_candidates": [
      {
        "activated_at": "string",
        "activated_by": "string",
        "activation_id": 0,
        "configuration_id": "string",
        "created_at": "string",
        "created_by": "string",
        "entries": [
          {
            "artifact_sha256": "string",
            "config_json": {},
            "configuration_id": "string",
            "enabled": true,
            "granted_capabilities": {
              "agent.badge.write": {
                "allowed_keys": []
              },
              "cid.resolve": {
                "max_bytes": 0
              },
              "http.request": {
                "allowed_methods": [],
                "allowed_url_prefixes": [],
                "max_inflight": 0,
                "max_request_bytes": 0,
                "max_response_bytes": 0,
                "timeout_ms": 0
              },
              "request.body.read": {
                "max_bytes": 0
              }
            },
            "hook": "request.start",
            "id": 0,
            "match": {
              "agent_id": {
                "operator": "exact",
                "value": "string"
              },
              "gateway_path": {
                "operator": "exact",
                "value": "string"
              },
              "method": {
                "operator": "exact",
                "value": "string"
              },
              "operation": {
                "operator": "exact",
                "value": "string"
              },
              "provider": {
                "operator": "exact",
                "value": "string"
              },
              "upstream_path": {
                "operator": "exact",
                "value": "string"
              }
            },
            "order_index": 0,
            "plugin_definition_id": 0,
            "plugin_id": "string",
            "plugin_mode": "enforcement",
            "plugin_version": "string",
            "runtime": "premade",
            "secret_ref_paths": [
              "string"
            ],
            "timeout_ms": 0
          }
        ],
        "entry_count": 0,
        "project_urn": "string",
        "project_uuid": "string",
        "status": "draft",
        "version": 0
      }
    ],
    "state": "active"
  }
}

400Bad Request

application/json

codestring
correlation_idstring
messagestring

Examplejson

{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

401Unauthorized

application/json

codestring
correlation_idstring
messagestring

Examplejson

{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

403Forbidden

application/json

codestring
correlation_idstring
messagestring

Examplejson

{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

404Not Found

application/json

codestring
correlation_idstring
messagestring

Examplejson

{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

500Internal Server Error

application/json

codestring
correlation_idstring
messagestring

Examplejson

{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}

503Plugin store unavailable, or Auth Service unreachable

application/json

codestring
correlation_idstring
messagestring

Examplejson

{
  "code": "string",
  "correlation_id": "string",
  "message": "string"
}