Create a delegation grant for an application or agent

POST

/v1/grants

const url = 'https://api.trustysweep.com/v1/grants';
const options = {
  method: 'POST',
  headers: {
    cookie: 'sweep_session=<sweep_session>',
    'Content-Type': 'application/json'
  },
  body: '{"principal_id":"example","operations":["discover"],"actions":["read_inventory"],"sources":["src_01J8Z3K9M2Q4R6S8T0V2W4X6Y8"],"containers":["example"],"max_objects_per_plan":1,"max_bytes_per_plan":1,"max_plans_per_day":1,"allowed_destinations":["dst_01J8Z3K9M2Q4R6S8T0V2W4X6Y8"],"allow_external_destinations":false,"allow_destructive":false,"allow_automatic":false,"require_human_approval_above":"read","min_confidence":0.85,"commercial_ceiling_cents":1,"expires_at":"2026-04-15T12:00:00Z","time_window":{"start_hour_utc":1,"end_hour_utc":1}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.trustysweep.com/v1/grants \
  --header 'Content-Type: application/json' \
  --cookie sweep_session=<sweep_session> \
  --data '{ "principal_id": "example", "operations": [ "discover" ], "actions": [ "read_inventory" ], "sources": [ "src_01J8Z3K9M2Q4R6S8T0V2W4X6Y8" ], "containers": [ "example" ], "max_objects_per_plan": 1, "max_bytes_per_plan": 1, "max_plans_per_day": 1, "allowed_destinations": [ "dst_01J8Z3K9M2Q4R6S8T0V2W4X6Y8" ], "allow_external_destinations": false, "allow_destructive": false, "allow_automatic": false, "require_human_approval_above": "read", "min_confidence": 0.85, "commercial_ceiling_cents": 1, "expires_at": "2026-04-15T12:00:00Z", "time_window": { "start_hour_utc": 1, "end_hour_utc": 1 } }'

Authorizations

sessionCookie
sessionToken

Parameters

Header Parameters

Idempotency-Key

string

<= 255 characters

Unique key per logical operation. Same key + same body within 24h replays the original response with Idempotent-Replayed: true; same key + different body → 409 idempotency_key_reused.

Request Body^required

application/json

object

principal_id

required

string

operations

required

Array<string>

>= 1 items

Allowed values: discover preserve write remove restore migrate monitor automate billable_execute

actions

required

Array<string>

>= 1 items

Allowed values: read_inventory read_quota read_vault search_vault create_plan preserve trash restore copy move migrate_external unsubscribe monitor automate manage_grants delete_vault_object delete_account permanent_delete

sources

One of:

Array<string>
null

Array<string>

containers

One of:

Array<string>
null

Array<string>

max_objects_per_plan

integer

max_bytes_per_plan

integer

max_plans_per_day

integer

allowed_destinations

One of:

Array<string>
null

Array<string>

allow_external_destinations

boolean

allow_destructive

boolean

allow_automatic

boolean

require_human_approval_above

string

Allowed values: read low medium high critical

min_confidence

number

default: 0.85

commercial_ceiling_cents

integer

expires_at

string format: date-time

time_window

One of:

object
null

object

start_hour_utc

integer

end_hour_utc

integer

Responses

201

Created

application/json

Versioned user delegation grant constraining what a principal may do on behalf of a user.

object

required

Prefixed ULID (grt_…)

string

/^grt_[0-9A-HJKMNP-TV-Z]{26}$/

version

required

integer

userId

required

string

tenantId

required

string

principalId

required

string

status

required

string

Allowed values: active revoked expired

createdAt

required

string format: date-time

expiresAt

One of:

string
null

string format: date-time

revokedAt

One of:

string
null

string format: date-time

operations

required

Array<string>

Allowed values: discover preserve write remove restore migrate monitor automate billable_execute

actions

required

Array<string>

sources

One of:

Array<string>
null

Array<string>

containers

One of:

Array<string>
null

Array<string>

assetKinds

One of:

Array<string>
null

Array<string>

maxObjectsPerPlan

One of:

integer
null

integer

maxBytesPerPlan

One of:

integer
null

integer

maxPlansPerDay

One of:

integer
null

integer

allowedDestinations

One of:

Array<string>
null

Array<string>

allowExternalDestinations

boolean

allowDestructive

boolean

allowAutomatic

boolean

requireShadowPlan

boolean

requireHumanApprovalAbove

string

Allowed values: read low medium high critical

minConfidence

number

commercialCeilingCents

One of:

integer
null

integer

timeWindow

One of:

object
null

object

startHourUtc

required

integer

endHourUtc

required

integer

Example

{
  "id": "grt_01J8Z3K9M2Q4R6S8T0V2W4X6Y8",
  "status": "active",
  "operations": [
    "discover"
  ],
  "actions": [
    "read_inventory"
  ],
  "requireHumanApprovalAbove": "read"
}

Headers

RateLimit-Limit

integer

Requests allowed in the current window.

RateLimit-Remaining

integer

Requests remaining in the current window.

RateLimit-Reset

integer

Seconds until the window resets.

400

Validation failed

application/problem+json

RFC 9457 problem details.

object

type

required

Https://developers.trustysweep.com/errors/

string format: uri

titlerequired

string

statusrequired

integer

detail

string

coderequired

Machine-readable error code from errors.json

string

request_idrequired

string

errors

Array<object>

object

pathrequired

string

messagerequired

string

`Example^generated`

{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

`401`

Section titled “401”

Unauthenticated

Media typeapplication/problem+json
RFC 9457 problem details.
object
typerequired
Https://developers.trustysweep.com/errors/

string format: uri
titlerequired
string
statusrequired
integer
detail
string
coderequired
Machine-readable error code from errors.json

string
request_idrequired
string
errors
Array<object>
object
pathrequired
string
messagerequired
string
Example^generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

`403`

Section titled “403”

Forbidden / action denied / step-up required

Media typeapplication/problem+json
RFC 9457 problem details.
object
typerequired
Https://developers.trustysweep.com/errors/

string format: uri
titlerequired
string
statusrequired
integer
detail
string
coderequired
Machine-readable error code from errors.json

string
request_idrequired
string
errors
Array<object>
object
pathrequired
string
messagerequired
string
Example^generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

`404`

Section titled “404”

Not found

Media typeapplication/problem+json
RFC 9457 problem details.
object
typerequired
Https://developers.trustysweep.com/errors/

string format: uri
titlerequired
string
statusrequired
integer
detail
string
coderequired
Machine-readable error code from errors.json

string
request_idrequired
string
errors
Array<object>
object
pathrequired
string
messagerequired
string
Example^generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

`409`

Section titled “409”

Conflict (state, stale plan, idempotency key reuse)

Media typeapplication/problem+json
RFC 9457 problem details.
object
typerequired
Https://developers.trustysweep.com/errors/

string format: uri
titlerequired
string
statusrequired
integer
detail
string
coderequired
Machine-readable error code from errors.json

string
request_idrequired
string
errors
Array<object>
object
pathrequired
string
messagerequired
string
Example^generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

`429`

Section titled “429”

Rate limited

Media typeapplication/problem+json
RFC 9457 problem details.
object
typerequired
Https://developers.trustysweep.com/errors/

string format: uri
titlerequired
string
statusrequired
integer
detail
string
coderequired
Machine-readable error code from errors.json

string
request_idrequired
string
errors
Array<object>
object
pathrequired
string
messagerequired
string
Example^generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

`Headers`

Section titled “Headers”

Retry-After

integer

Seconds to wait before retrying.

RateLimit-Limit

integer

Requests allowed in the current window.

RateLimit-Remaining

integer

Requests remaining in the current window.

RateLimit-Reset

integer

Seconds until the window resets.

`500`

Section titled “500”

Internal error

Media typeapplication/problem+json
RFC 9457 problem details.
object
typerequired
Https://developers.trustysweep.com/errors/

string format: uri
titlerequired
string
statusrequired
integer
detail
string
coderequired
Machine-readable error code from errors.json

string
request_idrequired
string
errors
Array<object>
object
pathrequired
string
messagerequired
string
Example^generated
{
  "type": "https://example.com",
  "title": "example",
  "status": 1,
  "detail": "example",
  "code": "example",
  "request_id": "example",
  "errors": [
    {
      "path": "example",
      "message": "example"
    }
  ]
}

Create a delegation grant for an application or agent

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Responses

201

Example

Headers

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

404

Examplegenerated

409

Examplegenerated

429

Examplegenerated

Headers

500

Examplegenerated

Request Body^required

`Example^generated`

`401`

`Example^generated`

`403`

`Example^generated`

`404`

`Example^generated`

`409`

`Example^generated`

`429`

`Example^generated`

`Headers`

`500`

`Example^generated`