---
title: "Create a managed space grant"
method: POST
path: "/v1/spaces/{spaceId}/grants"
tags: ["Access"]
---

# Create a managed space grant

`POST /v1/spaces/{spaceId}/grants`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/spaces/{spaceId}/grants`
- Auth: HTTP bearer

Gives an audience access to a Space or path. Use it to make a Space public, or to share it with the team or one person. The body names the audience: public, team, person, or an external identity that one of the team's identity connections authenticates. The response includes the runtime update when it continues in the background. A grant whose point is commenting (`comments.write` without `content.publish` or `access.manage`) must target where Comments run: a live target needs the Space's comments surface set to `everywhere`. Otherwise 422 `comments_target_unavailable`.

## Path parameters

- `spaceId` string, required

## Request body

- object
  - `name` string
  - `audience` union, required
    - object
      - `kind` 'public', required
    - object
      - `kind` 'team', required
      - `teamId` string, required
    - object
      - `kind` 'person', required
      - `personId` string, required
    - object
      - `kind` 'external', required
      - `connectionId` string, required
      - `subject` string, required
  - `resources` object, required
    - `include` string[], required
    - `exclude` string[]
  - `capabilities` string[], required
  - `constraints` object
    - `notBefore` union
      - string, date-time
      - string
    - `expiresAt` union
      - string, date-time
      - string
    - `maxUses` integer
    - `requireVerifiedEmail` boolean
    - `network` object
      - `ipCidrs` string[]: IP address and CIDR Grants are unsupported because the serving runtime has no trusted visitor IP. Remove the IP constraint.
      - `countries` string[]
      - `excludedCountries` string[]
      - `excludedUserAgentSubstrings` string[]
    - `frameOrigin` string
  - `target` union, required
    - object
      - `kind` 'live', required
    - object
      - `kind` 'version', required
      - `versionId` string, required
    - object
      - `kind` 'branch', required
      - `branch` string, required
    - object
      - `kind` 'all_versions', required

## Response `201`

Response for status 201

- object
  - `$schema` string, uri: Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
  - `data` object, required
    - `grant` object, required
      - `name` string
      - `audience` union, required
        - object
          - `kind` 'public', required
        - object
          - `kind` 'team', required
          - `teamId` string, required
        - object
          - `kind` 'person', required
          - `personId` string, required
        - object
          - `kind` 'link', required
          - `linkId` string, required
        - object
          - `kind` 'password', required
          - `credentialId` string, required
        - object
          - `kind` 'machine', required
          - `machineId` string, required
        - object
          - `kind` 'external', required
          - `issuer` string, required
          - `subject` string, required
      - `resources` object, required
        - `include` string[], required
        - `exclude` string[], required
      - `capabilities` string[], required
      - `constraints` object, required
        - `notBefore` union
          - string, date-time
          - string
        - `expiresAt` union
          - string, date-time
          - string
        - `maxUses` integer
        - `requireVerifiedEmail` boolean
        - `network` object
          - `ipCidrs` string[]: IP address and CIDR Grants are unsupported because the serving runtime has no trusted visitor IP. Remove the IP constraint.
          - `countries` string[]
          - `excludedCountries` string[]
          - `excludedUserAgentSubstrings` string[]
        - `frameOrigin` string
      - `target` union, required
        - object
          - `kind` 'live', required
        - object
          - `kind` 'version', required
          - `versionId` string, required
        - object
          - `kind` 'branch', required
          - `branch` string, required
        - object
          - `kind` 'all_versions', required
      - `id` string, required
      - `source` object, required
        - `kind` 'config' | 'managed' | 'system', required
        - `reference` string, required
    - `generation` integer, required
    - `status` 'scheduled' | 'active' | 'expired', required
    - `sourceExplanation` object, required
      - `editable` boolean, required
      - `label` string, required
      - `detail` string, required
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
  - `operation` object, nullable, required: Background operation handle when asynchronous work remains after this mutation; null when it completed synchronously.
    - `id` string, required
    - `kind` string, required
    - `status` 'queued' | 'running' | 'succeeded' | 'failed' | 'canceled', required
    - `resources` object[], required
      - `type` string, required
      - `id` string, required
    - `progress` object
      - `total` integer, required
      - `completed` integer, required
      - `failed` integer, required
    - `diagnostics` object[]
      - `code` string, required: Stable snake_case diagnostic code naming the public contract that produced it.
      - `severity` 'info' | 'warning' | 'error', required: How actionable the diagnostic is.
      - `message` string, required: Human-readable explanation with enough detail to act on.
      - `path` string, nullable: Artifact path the diagnostic points at, for example "_headers:12", when one exists.
      - `provider` 'infra' | 'dns' | 'registrar' | 'runtime', nullable: Upstream system the diagnostic originated from, when not Spacefast itself.
      - `details` object, nullable: Machine-readable context for the diagnostic code.
      - `fix` string, nullable: Concrete, agent-actionable remediation hint, when one can be derived.
      - `retryable` boolean, nullable: Whether retrying the same operation can resolve this diagnostic without the caller changing anything.
    - `createdAt` string, date-time, required
    - `finishedAt` string, date-time

## Other responses

- `default`: Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

---

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