Skip to main content

Organization API Keys

An organization key reaches current and future Workspaces in that organization. It uses an Integration Member in each Workspace rather than the creating person's Workspace memberships.

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

Create a key​

Navigate to Organization > API Keys.

  1. Click Create API Key and give it a name that says which integration holds it.
  2. Choose scopes. The key's scopes are its ceiling: it can never do more than you select here, on any workspace.
  3. (Optional) Set an expiration date.
  4. Confirm the creation and complete the 2FA (a fresh prompt — you will be asked to confirm your second factor when you create the key) prompt. Minting a credential that reaches every workspace in the organization is an org-admin action and always requires a recent second factor.
  5. Store the secret now — it is shown once. Copy it into your secrets manager before you leave the page; it cannot be displayed again.

What happens on first use​

The first time the key calls a workspace in your organization, 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; you also do not need to re-create the key when a new workspace is created.

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. 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. 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.

Revoke a key​

Open Organization → 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.