List the policy gate signing keys

Embed
Preview of the card
<a href="https://forumulate.com/reference/forumulate-api-policygateadmin-listkeys"><img src="https://forumulate.com/reference/_api/public/orgs/046a9bc0-d530-43ae-9bae-af7945008cda/spaces/8042f004-e3d9-445f-b7a4-b6c1f86836e6/pages/7f280821-4043-42c3-8dd6-aa963c9405ce/social-card.svg?v=3e7ae33eec8b" alt="List the policy gate signing keys" width="600" height="315"></a>
GEThttps://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/policy-gate/keys

The space’s keyring: which key signs (primary), which still verify (active), and when a rotated key retires. Never a secret.

Requires token scope: read — see "Token scopes" under Authentication.

From Forumulate-Version: 2027-01-01 this list answers its rows once, under data (the named key is gone), leaves the document bodies (markdown, sections, content, html) out of each row unless include names them, and keeps only the fields you list. Earlier versions are unchanged. See /reference/versioning.

Parameters

orgIdstringpathrequired
The organization: its uuid, or its slug. One you are not a member of is a 404.
spaceIdstringpathrequired
The space: its uuid, or its slug within the organization. An id further down the path that belongs to a DIFFERENT space is a 404, not a cross-space read.
forumulate-versionstringheader
API version negotiation. Send forumulate-version: 2027-03-01 on every request from a new integration; it is optional only so that integrations written before versioning keep working. Each version includes everything before it:
limitintegerquery
Rows per page. Defaults to 100. 500 is the most this endpoint serves — a larger value is capped, not refused. A value that is not a whole number of 1 or more is a 422, never a silent default.
= 100
cursorstringquery
Where to continue from: pass back the page.nextCursor of the previous answer. Opaque — there is nothing inside one to construct or parse. Sending one also opts into the enveloped shape, exactly as stating Forumulate-Version does.
includestring[]query
From 2027-01-01: the document bodies to keep in each row, comma-separated. An unknown name is a 422 naming the nearest one. Ignored by earlier versions, which always send the bodies.
fieldsstring[]query
From 2027-01-01: the only keys to return in each row, comma-separated (id always comes back; naming a body field brings it back). A name no row on the page carries is a 422 with a did-you-mean. Ignored by earlier versions.

Code samples

cURL
curl -X GET "https://forumulate.com/api/orgs/{orgId}/spaces/{spaceId}/policy-gate/keys" \
  -H "Authorization: Bearer $FORUMULATE_API_KEY" \
  -H "forumulate-version: <value>"
TypeScript
Python
Go
PHP
Ruby
Java

Responses

200 Success.
Example
{
  "keys": [
    {
      "active": true,
      "createdAt": "string",
      "kid": "string",
      "primary": true,
      "retiresAt": "string",
      "revokedAt": "string"
    }
  ],
  "page": {
    "limit": 0,
    "hasMore": true,
    "nextCursor": "string",
    "has_more": true,
    "next_cursor": "string",
    "total": 0
  },
  "data": [
    {
      "active": true,
      "createdAt": "string",
      "kid": "string",
      "primary": true,
      "retiresAt": "string",
      "revokedAt": "string"
    }
  ]
}
Schema
keysPolicyGateKeySummary[]
Absent from 2027-01-01: read data.
Show child parameters
activebooleanrequired
createdAtstringrequired
kidstringrequired
primarybooleanrequired
retiresAtstringrequired
revokedAtstringrequired
pageobject
The paging envelope a collection carries when the caller states Forumulate-Version. Each operation’s own response schema says whether it has one: a collection either carries page, or answers both this and its pre-envelope shape and picks by the header. No listing pages with keys of its own any more — the allowlists in openapi-collection-shape.test.ts are empty, which is what stops a new one from appearing. Read hasMore and nextCursor: the snake_case pair beside them is deprecated and is not sent to a caller who states 2026-11-01 or later.
Show child parameters
limitintegerrequired
The limit this page was built with — what was asked for, capped. NOT the number of rows returned: a final page under the limit is normal, and hasMore is the only thing that says whether to keep walking.
hasMorebooleanrequired
Whether another page follows this one.
nextCursorstringrequired
Pass back as cursor to continue. Null on the last page.
has_morebooleandeprecated
The same value as hasMore. These two are the only snake_case keys in the API. Sent to callers who state 2026-09-01 or no version at all; ABSENT from 2026-11-01 onwards. Read hasMore instead — it is sent on every version.
next_cursorstringdeprecated
The same value as nextCursor. Absent from 2026-11-01 onwards; read nextCursor.
totalinteger
Rows in the whole collection — the size of the set, not of this page, and not of what you have seen so far. ABSENT where the source cannot count the collection: the append-only logs (staff actions, automation runs, connector activity, ingested questions, chat history) grow without bound and are not counted on every page view. Walk on hasMore, which is exact on every answer; read total only to show a size, and handle its absence.
dataPolicyGateKeySummary[]
The same rows as the key named after them (topics, articles, pages, monitors, …), under a key that is the same on every paged list — so one parser reads every collection. The SAME array, not a different selection: read either. Present whenever page is, i.e. when you state Forumulate-Version (or send a cursor); the unversioned shape does not carry it.
Show child parameters
activebooleanrequired
createdAtstringrequired
kidstringrequired
primarybooleanrequired
retiresAtstringrequired
revokedAtstringrequired
400 The request could not be understood — a malformed header, path or query value (request.malformed). A value that was understood but is not acceptable is a 422 validation.failed.
Example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {},
    "docs": "string",
    "reason": "string",
    "slugs": [
      "string"
    ],
    "conflict": {
      "etag": "string",
      "ops": [
        {}
      ]
    }
  },
  "requestId": "string"
}
Schema
errorobjectrequired
Show child parameters
codestringrequired
Stable, machine-readable error code, e.g. rbac.forbidden.
messagestringrequired
Human-readable explanation.
detailsobject
Field-level validation problems, keyed by field path (422 only).
docsstring
Where the vocabulary or format this error is about is published — an absolute URL, or an API route such as GET /space-types/{type}/presets. Present on errors over a controlled list, so the answer to "what am I allowed to send?" is in the error itself.
reasonstring
Why a credential was refused, as one stable word, where one status has several causes — e.g. an external_jwt redeem answers iat_too_old, iat_in_future, bad_signature, bad_issuer, bad_audience, expired and more. Branch on this, not on message.
slugsstring[]
The exact slugs that collided, on a slug-conflict 409 — space.slug_taken, page.slug_taken, collection.slug_taken, site.slug_taken or badge.slug_taken.
conflictobject
On a 409 from a content entry field write (PATCH …/entries/{entryId}/fields) whose If-Match was stale.
Show child parameters
etagstringrequired
The entry's current fields etag.
opsarrayrequired
The field operations since your If-Match that touch a path your own operations touch. Empty: none did — retry the batch unchanged under etag. null: the history no longer reaches your tag — re-read the entry first.
requestIdstring
The id of this request — the same value as the x-request-id and x-forumulate-request-id response headers. Quote it in a bug report: it is the only thing that finds your exact request in our logs. It is in the body because that is the part that survives — an SDK that throws the parsed body, a serverless log that keeps the body and drops the headers, a ticket with the JSON pasted in.
401 No credential, or one that is expired or revoked (auth.required). Send a Bearer token or the session cookie.

Same as 400 · GET /orgs/{orgId}/spaces/{spaceId}/policy-gate/keys

403 Authenticated, and not allowed — always rbac.forbidden, whether what is missing is the capability, the token scope, or a resource the token is pinned away from. The message names the capability and, for a scope refusal, the scopes that would grant it. A refusal because of the PLAN is a 402 with quota.exceeded, not this.

Same as 400 · GET /orgs/{orgId}/spaces/{spaceId}/policy-gate/keys

404 No such thing — one of the ids in the path does not resolve, or resolves to something this caller may not see (*.not_found).

Same as 400 · GET /orgs/{orgId}/spaces/{spaceId}/policy-gate/keys

429 Rate limited — see the RateLimit-* headers.

Same as 400 · GET /orgs/{orgId}/spaces/{spaceId}/policy-gate/keys

default Error — the stable { error: { code, message } } envelope.

Same as 400 · GET /orgs/{orgId}/spaces/{spaceId}/policy-gate/keys

The Forumulate teamUpdated