Depot effectiveconfig

Registers the effective-config route on mux.

This page is generated from the Depot route table. Every operation carries the permission it needs and the anchor an agent can link to.

GET /api/v1/endpoints/{agentID}/policy/effective

GETpolicy:readtenant facehosteditmspremoteIdempotent

From an MSP console, prefix the path with /api/v1/clients/{clientID} to reach one client.

Source: [object Object]

Get effective config

Parameters

Name	In	Type	Required	Description
agentID	path	string	Yes	A uuid.
explain	query	string	No
namedUserId	query	string	No

Responses

Status	Body	Description
200	application/json, EffectiveConfigView	Success.
400	application/problem+json, ProblemDetails	One or more validation errors occurred.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold policy:read.
404	application/problem+json, ProblemDetails	No resource matches that id.
500	application/problem+json, ProblemDetails	No client store in request context.

200 response body

Field	Type	Description
agentIdrequired	string
enforcement	EnforcementReportView	enforcementReportView is the endpoint's newest word on this configuration.
enforcement.moderequired	string
enforcement.policyHashrequired	string
enforcement.reportedAtrequired	string (date-time)
enforcement.stale	boolean
enforcement.statusesrequired	object
hashrequired	string
issues	array of EffectiveIssueView
issues[].detail	string
issues[].key	string
issues[].kindrequired	string
issues[].profileIds	array of string
namedUserId	string
osFamily	string
profiles	array of EffectiveProfileView
profiles[].mandatoryrequired	boolean
profiles[].profileIdrequired	string
profiles[].profileNamerequired	string
profiles[].rankrequired	integer
settingsrequired	object
targetFrameworksrequired	array of string

Request samples

curl

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X GET 'https://depot.example.com/api/v1/endpoints/<agentID>/policy/effective?explain=<explain>&namedUserId=<namedUserId>' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -b 'outpost_console=<console-session>'

PowerShell

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$response = Invoke-RestMethod `
    -Method Get `
    -Uri 'https://depot.example.com/api/v1/endpoints/<agentID>/policy/effective?explain=<explain>&namedUserId=<namedUserId>' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10

Python

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/endpoints/<agentID>/policy/effective"
params = {
    "explain": "<explain>",
    "namedUserId": "<namedUserId>",
}
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.get(url, params=params, headers=headers, cookies=cookies, timeout=30)
response.raise_for_status()
print(response.json())

Go

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

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

func main() {
  req, err := http.NewRequest(http.MethodGet, "https://depot.example.com/api/v1/endpoints/<agentID>/policy/effective?explain=<explain>&namedUserId=<namedUserId>", nil)
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("X-CSRF-Token", "<csrf-token>")
  req.Header.Set("Accept", "application/json")
  req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()

  out, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(resp.Status, string(out))
}

TypeScript

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
// The session cookie is set by signing in. A script cannot set it itself.

const url = new URL("https://depot.example.com/api/v1/endpoints/<agentID>/policy/effective");
url.searchParams.set("explain", "<explain>");
url.searchParams.set("namedUserId", "<namedUserId>");

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
  },
  credentials: "include",
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

C#

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://depot.example.com/api/v1/endpoints/<agentID>/policy/effective?explain=<explain>&namedUserId=<namedUserId>");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());