Authentication

Every authenticated API request resolves to a principal. Authorization then evaluates the principal type, organization boundary, scopes, resource visibility, ownership, and role.

Service principals

Use a service principal for server-to-server automation owned by an organization. Its API key uses the gsmc_sk_ prefix and is sent as a Bearer token.

Service principals have no human membership. Their access comes from scopes and, when configured, a resource allowlist. They cannot administer other service principals.

Private resources are invisible to service principals

Scopes are not sufficient on their own. A service principal can never read or invoke a resource whose visibility is private, no matter which scopes it holds — the visibility check runs first and denies outright.

Agents, pipelines, and chats are created private by default, so a new automation account typically sees nothing until you act:

• share the resource with the organization, which makes it visible to every member and to organization-owned automation; or
• set the resource to restricted visibility and grant the service principal explicit access — for restricted resources, scope plus grant are both required.

Plan for this before granting scopes. A correctly scoped key against private resources produces an empty list, not an error.

Delegated clients and tokens

Use delegated access when an external application acts on behalf of a specific user. Delegated tokens use the gsmc_dt_ prefix, carry the user's identity for attribution and ownership, and remain restricted by granted scopes.

A delegate is not a stand-in for the user's full account. Its effective role is capped at member even when the underlying user is an organization admin or owner, so a delegated token never inherits administrative powers. It reaches resources through the user's ownership and its own scope grant.

Delegated access is appropriate when attribution and the user's own resources matter. It is not a substitute for an organization-owned background integration, and not a way to script admin operations.

Human sessions

The web application uses short-lived access tokens and a backend-managed HttpOnly refresh cookie. Do not copy browser credentials into an integration.

Key handling

• Store keys in a secret manager.
• Use separate principals for separate systems.
• Grant the narrowest useful scopes.
• Rotate keys without reusing names or values.
• Revoke a key immediately if it may have leaked.
• Never expose service-principal keys to client-side JavaScript.