Skip to main content

Organization API Keys

An organization key belongs to the organization, not to the person who creates it. By default it reaches every current and future Workspace in the organization. You can instead limit it, when you create it, to chosen Workspaces, to Workspaces that carry certain labels, or both. In each Workspace it reaches, it acts as an Integration Member rather than through the creating person's Workspace memberships.

For a personal or account-owned integration, see Account API Keys.

Create a key​

Navigate to Organization > Settings > API Keys.

  1. Click Create API Key and give it a name that says which integration holds it. The name is required.
  2. (Optional) Set how many days the key lasts, from 1 to 365.
  3. Choose which Workspaces the key reaches: All workspaces (including ones created later), Selected workspaces (pick Workspaces, labels, or both; see Limit a key to some Workspaces), or No workspaces. The line under the choices shows how many Workspaces the choice reaches right now.
  4. Choose scopes, below the Workspaces. The key's scopes are its ceiling: it can never do more than you select here, on any workspace.
  5. Confirm the creation and complete any verification prompt. Creating an organization key requires recent MFA, satisfied by a device-verified passkey or a completed second factor.
  6. Store the secret now — it is shown once. Copy it into your secrets manager before you leave the page; it cannot be displayed again.

Limit a key to some Workspaces​

A limited key uses the same Workspace and label choices as an organization webhook endpoint.

  • Chosen Workspaces. The key reaches each Workspace you pick. A Workspace created later is not added.
  • Labels. The key reaches every Workspace that carries all of the labels you pick: choosing production and sponsor-acme reaches only Workspaces labelled both. This includes Workspaces that get those labels later.
  • Both. The key reaches the Workspaces you picked plus the labelled ones. A picked Workspace stays reachable even if it loses a label.

You can pick up to 100 Workspaces and up to 10 labels.

Labels are checked on every request. When a Workspace gains all of the key's labels, its next request is accepted; when it loses one, its next request is refused, unless you also picked that Workspace. Requests already in progress are not stopped.

Selected workspaces must name at least one Workspace or label; Create API Key stays disabled until it does. If every Workspace you picked is later deleted and the key has no labels, the key reaches no Workspaces and its card says No workspaces.

A Workspace outside the key's selection refuses it with 403 Forbidden. A Workspace in another organization answers 404 Not Found, as before.

Changing which Workspaces a key reaches​

A key's Workspaces are fixed when it is created and shown read-only on its card. To change them, create a replacement key with the selection you want, move your integration to the new secret, then revoke the old key.

A label that any organization key's selection uses cannot be deleted from Workspace Labels: deleting it would widen what the key reaches. The delete button is disabled and explains why. Revoke or replace the key first. This includes disabled and expired keys until they are revoked.

When a key was created during an update​

If you limit a key while Gravity Rail is being updated, the server that handles the request may not yet understand Workspace limits and may create a key for every Workspace instead. When that happens the page does not show the secret: it revokes that key and asks you to try again. If revoking it also fails, the message names the key; revoke it from the list yourself.

What happens on first use​

The first time the key calls a workspace it reaches, Gravity Rail provisions an Integration member in that workspace and records it on the workspace's activity feed. Later calls reuse that member, so nothing is created twice. You do not need to add the key to a workspace in advance. A key for every Workspace does not need to be re-created when a new workspace is created, and a label-limited key picks up new Workspaces that carry its labels.

All of an organization's keys share that one Integration member per workspace. A key whose selection does not include a workspace is refused there before anything is created, and it never removes or changes a member that another key created. Limiting a key never re-enables a member or access that has been paused.

To pause the key in one workspace, a workspace administrator with the members:admin scope can archive its Integration member. The key is refused in that workspace until the member is restored, while its other workspaces remain available. Because the member is shared, this pauses every organization key in that workspace. For a durable suspension, contact support to suspend the credential's access to that workspace. Permanently deleting an archived Integration member does not suspend access: the key provisions a fresh member on its next call.

Data use and PHI​

Gravity Rail works out a key's data-use posture when the key is created, by looking at this organization's workspaces at that moment — all of them, even for a limited key. If any of them requires PHI authorization, the organization key is issued as a no-PHI key. A key's posture can only ever be narrowed after creation, never widened — a key that cannot carry PHI can never silently become one that can. If your integration must handle PHI, contact support before you design it around an organization key.

Where an organization key works​

An organization key calls a Workspace's REST API (/api/v2/w/{workspace_uuid}/…). It is not accepted on organization settings routes (/api/v2/o/…) or on realtime connections, whether or not it is limited.

Use the command line​

gr org api calls the same organization routes the settings page uses.

List the organization's keys, each with its workspaceScope: a mode (all, selected or none), workspaceUuids and labelSelector. The secret is never listed.

gr org api --org $ORG_UUID --path /api-keys

A create request takes the same fields as the page and a required workspaceScope. Send {"mode": "all"} for a key that reaches every Workspace, {"mode": "none"} for one that reaches none, or {"mode": "selected", ...} with workspaceUuids (up to 100 Workspace UUIDs of this organization) and/or labelSelector (up to 10 existing label slugs). A longer list is refused with 422. An unknown or other-organization Workspace or label is refused with 400 and no key is created.

gr org api --org $ORG_UUID --path /api-keys --method POST --allow-write --data '{
"name": "Sponsor Acme pipeline",
"scopes": ["members:read", "records:read"],
"expiresInDays": 90,
"workspaceScope": {
"mode": "selected",
"workspaceUuids": ["<workspace-uuid>"],
"labelSelector": ["production", "sponsor-acme"]
}
}'

Creating and revoking a key are actions a person takes: they need an interactive sign-in by an organization admin, and creating one needs MFA completed within the last five minutes. API keys and OAuth tokens, including the token gr login stores, are refused, so create and revoke keys from Organization > Settings > API Keys. A server that does not yet understand the workspace scope ignores it; check that the response's workspaceScope.mode is the mode you asked for before you use the key.

Revoke a key​

Open Organization → Settings → API Keys and revoke a key that is no longer required. Revocation invalidates the credential across the organization.

See Store keys securely for secret handling, and the Authentication guide for API requests.