Introducing Portals: Authenticated endpoints for GraphQL operations

Buildkite Portals are user-defined GraphQL operations exposed via authenticated URL endpoints — offering a new, secure way to access the Buildkite API.

Designed with machine-to-machine operations in mind, Portals are not tied to user-owned access tokens. Instead, they use ephemeral, scoped tokens that can only perform the operations defined in an approved GraphQL document.

Key benefits of Portals include:

• Scoped access — Tokens are restricted to the exact operations defined by organization admins. This enables fine-grained, least-privilege access to your Buildkite data.
• Ephemeral tokens — Tokens are short-lived and single-purpose, ideal for secure machine-to-machine communication.
• User-invoked flow — Optional interactive flows allow users to generate tokens on-demand, similar to OAuth.
• Userless authentication — Tokens are not tied to any individual user, avoiding disruptions if team members are removed.

Getting started with Portals

Portals can be created by administrators from organization settings page. Each portal is assigned a unique endpoint with the following URL structure: https://portal.buildkite.com/organizations/{organization.slug}/portals/{portal.slug}

Portals support passing variables to enable dynamic operations and offer multiple authentication mechanisms for flexibility and security.

For more information, see the Portals documentation.