---
title: "Decide a suspension"
method: POST
path: "/access-suspensions/{id}/decision"
tags: ["Roles and members"]
---

# Decide a suspension

`POST /access-suspensions/{id}/decision`

## Request

- Base URL: `https://api.primitive.dev/v1`
- URL: `https://api.primitive.dev/v1/access-suspensions/{id}/decision`
- Auth: HTTP bearer

Keep, narrow or revoke one suspended or flagged item. Keeping it, and revoking an API key, needs the decider to cover it (revoking an uncovered key is refused with `grant_forbidden`, `target_not_covered`). Keeping an API key rotated (`rotate: true`, other than the shared Function key) also revokes its older secrets still in a rotation overlap, and needs keys:manage on both the credential and the person: without it, or if the decider lost members:manage meanwhile, it is refused with `grant_forbidden` (`keys_manage_required` or `actor_access_changed`) and nothing is rotated. Person only: a dashboard session, or the person's own OAuth or CLI token with a session step-up of purpose `suspensions.decide` (the person confirms at the step_up_url a 403 step_up_required answer carries, which names this client, then send the token in the Primitive-Step-Up header; the token works only with the client it was confirmed for). Needs members:manage. API keys are refused.

## Path parameters

- `id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- DecideSuspensionRequest
  - `decision` 'keep' | 'narrow' | 'revoke', required
  - `grant` union
    - 'super_admin' | 'send_only' | 'read_only' | 'own_addresses' | 'own_addresses_read_only' | 'custom'
    - object
      - `preset` 'super_admin' | 'send_only' | 'read_only' | 'own_addresses' | 'own_addresses_read_only' | 'custom', required
      - `matrix` object
      - `permissions` string[]
      - `addresses` string[]
      - `domains` string[]
      - `rules` string[]
      - `depth` 'metadata' | 'content' | 'raw'
      - `resources` object
      - `mail_scope` 'org'
  - `confirm` boolean
  - `rotate` boolean

## Response `200`

Decide a suspension

- object
  - `success` true, required
  - `data` DecideSuspensionResult, required
    - `id` string, required
    - `decision` 'keep' | 'narrow' | 'revoke', required
    - `function_stopped` object
      - `by` 'owner_or_admin', required
      - `stop_rank` 'owner' | 'admin', required
      - `message` string, required

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key
- `403`: Authenticated caller lacks permission for the operation
- `404`: feature_disabled: the feature is not enabled for the organization; or not_found: the item the path names does not exist.
- `409`: conflict: the item changed while you edited it, or a member was removed and added back. Look again, then retry.
- `429`: Rate limit exceeded. The `ratelimit-*` headers describe the limiter that rejected this request, with its own limit and window, not the API budget that successful responses report. A limiter that reports only a wait sends `Retry-After` alone.

---

[API](https://skmtc.dev/primitive/apis/primitive-api.md) - [All operations](https://skmtc.dev/primitive/apis/primitive-api/llms.txt) - [OpenAPI document](https://skmtc.dev/primitive/apis/primitive-api/revisions/bce409c97acb?raw)