---
title: "Explain effective grant access"
method: GET
path: "/v1/spaces/{spaceId}/grants/check"
tags: ["Access"]
---

# Explain effective grant access

`GET /v1/spaces/{spaceId}/grants/check`

## Request

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

Evaluates one route and target for any grant audience and returns additive capabilities, matching grants, and failed checks for every candidate.

## Path parameters

- `spaceId` string, required

## Query parameters

- `path` string: Request path to simulate, for example `/admin`.
- `target` 'live' | 'version' | 'branch': Which deployment the visit lands on: the live channel, one version, or a branch.
- `targetId` string: The version id or branch name named by `target`. Required for `version` and `branch`, and rejected for `live`.
- `audience` 'public' | 'team' | 'person' | 'link' | 'password' | 'machine' | 'external': Who is knocking. Each audience needs its own identifying parameter below, and rejects the others.
- `personId` string: The person to simulate. Required with `audience=person`.
- `linkId` string: The share link to simulate. Required with `audience=link`.
- `passwordCredentialId` string: The password credential to simulate. Required with `audience=password`.
- `machineId` string: The machine credential to simulate. Required with `audience=machine`.
- `issuer` string: Identity connection issuer for the external identity to simulate. Required with `audience=external`.
- `subject` string: Subject claim of the external identity to simulate. Required with `audience=external`.
- `verifiedEmail` 'true' | 'false': Whether the simulated visitor's email counts as verified.
- `ipAddress` string: Hypothetical client IP. IP-constrained Grants remain unsupported and denied.

## Response `200`

Response for status 200

- 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
    - `path` string, required
    - `target` union, required
      - object
        - `kind` 'live', required
      - object
        - `kind` 'version', required
        - `versionId` string, required
      - object
        - `kind` 'branch', required
        - `branch` string, required
    - `simulatedAudience` 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
    - `capabilities` string[], required
    - `matchingGrants` object[], required
      - `grant` object, required
        - `grant` object, required
          - `name` string
          - `audience` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `resources` object, required
            - `include` string[], required
            - `exclude` string[], required
          - `capabilities` string[], required
          - `constraints` object, required
            - `notBefore` union
              - …
            - `expiresAt` union
              - …
            - `maxUses` integer
            - `requireVerifiedEmail` boolean
            - `network` object
              - …
            - `frameOrigin` string
          - `target` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `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
      - `capabilities` string[], required
    - `evaluatedGrants` object[], required
      - `grant` object, required
        - `grant` object, required
          - `name` string
          - `audience` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `resources` object, required
            - `include` string[], required
            - `exclude` string[], required
          - `capabilities` string[], required
          - `constraints` object, required
            - `notBefore` union
              - …
            - `expiresAt` union
              - …
            - `maxUses` integer
            - `requireVerifiedEmail` boolean
            - `network` object
              - …
            - `frameOrigin` string
          - `target` union, required
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
          - `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
      - `failures` string[], required

## 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)