Organizations
A collection of common tasks with organizations using the GraphQL API.
You can test out the Buildkite GraphQL API using the Buildkite explorer. This includes built-in documentation under the Docs panel.
List organization members
List the first 100 members in the organization.
query getOrgMembers{
organization(slug: "organization-slug") {
members(first: 100) {
edges {
node {
role
user {
name
email
id
}
}
}
}
}
}
Search for organization members
Look up organization members using their email address.
query getOrgMember{
organization(slug: "organization-slug") {
members(first: 1, search: "user-email") {
edges {
node {
role
user {
name
email
id
}
}
}
}
}
}
Get the most recent SSO sign-in for all users
Use this to get the last sign-in date for users in your organization, if your organization has SSO enabled.
query getRecentSignOn {
organization(slug: "organization-slug") {
members(first: 100) {
edges {
node {
user {
name
email
}
sso {
authorizations(first: 1) {
edges {
node {
createdAt
expiredAt
}
}
}
}
}
}
}
}
}
Update the default SSO provider session duration
You can control how long the session can go before the user must revalidate with your SSO. By default that's indefinite, but you can reduce it down to hours or days.
mutation UpdateSessionDuration {
ssoProviderUpdate(input: { id: "ID", sessionDurationInHours: 2 }) {
ssoProvider {
sessionDurationInHours
}
}
}
Update inactive API token revocation
On the Enterprise plan, you can control when inactive API tokens are revoked. By default, they are never (NEVER) revoked, but you can set your token revocation to either 30, 60, 90, 180, or 365 days.
mutation UpdateRevokeInactiveTokenPeriod {
organizationRevokeInactiveTokensAfterUpdate(input: {
organizationId: "organization-id",
revokeInactiveTokensAfter: DAYS_30
}) {
organization {
revokeInactiveTokensAfter
}
}
}
Pin SSO sessions to IP addresses
You can require users to re-authenticate with your SSO provider when their IP address changes with the following call, replacing ID with the GraphQL ID of the SSO provider:
mutation UpdateSessionIPAddressPinning {
ssoProviderUpdate(input: { id: "ID", pinSessionToIpAddress: true }) {
ssoProvider {
pinSessionToIpAddress
}
}
}
Enforce two-factor authentication (2FA) for your organization
Require users to have two-factor authentication enabled before they can access your organization's Buildkite dashboard.
mutation EnableEnforced2FA {
organizationEnforceTwoFactorAuthenticationForMembersUpdate(
input: {
organizationId: "organization-id",
membersRequireTwoFactorAuthentication: true
}
) {
organization {
id
membersRequireTwoFactorAuthentication
uuid
}
}
}
Query the usage API
Use the usage API to query your organization's usage by pipeline or test suite at daily granularity.
query Usage {
organization(slug: "organization-slug") {
id
name
usage(
aggregatedOnFrom: "2023-04-01"
aggregatedOnTo: "2023-05-01"
resource: [JOB_MINUTES, TEST_EXECUTIONS]
) {
edges {
node {
__typename ... on JobMinutesUsage {
aggregatedOn
seconds
pipeline {
name
id
}
}
}
node {
__typename ... on TestExecutionsUsage {
Time: aggregatedOn
executions
suite {
name
id
}
}
}
}
pageInfo {
endCursor
hasNextPage
}
}
}
}
Create a user, add them to a team, and set user permissions
Invite a new user to the organization, add them to a team, and set their role.
First, get the organization and team ID:
query getOrganizationAndTeamId {
organization(slug: "organization-slug") {
id
teams(first:500) {
edges {
node {
id
slug
}
}
}
}
}
Then invite the user and add them to a team, setting their role to 'maintainer':
mutation CreateUser {
organizationInvitationCreate(input: {
organizationID: "organization-id",
emails: ["user-email"],
role: MEMBER,
teams: [
{
id: "team-id",
role: MAINTAINER
}
]
}) {
invitationEdges {
node {
email
createdAt
}
}
}
}
Delete an organization member
This deletes a member from an organization. It does not delete their Buildkite user account.
First, find the member's ID:
query getOrganizationMemberIds {
organization(slug: "organization-slug") {
members(search: "organization-member-name", first: 10) {
edges {
node {
role
user {
name
}
id
}
}
}
}
}
Then, use the ID to delete the user:
mutation deleteOrgMember {
organizationMemberDelete(input: { id: "organization-member-id" }){
organization{
name
}
deletedOrganizationMemberID
user{
name
}
}
}
Get organization audit events
Query your organization's audit events. Audit events are only available to Enterprise customers.
query getOrganizationAuditEvents{
organization(slug:"organization-slug"){
auditEvents(first: 500){
edges{
node{
type
occurredAt
actor{
name
}
subject{
name
type
}
}
}
}
}
}
To get all audit events in a given period, use the occurredAtFrom and occurredAtTo filters like in the following query:
query getTimeScopedOrganizationAuditEvents{
organization(slug:"organization-slug"){
auditEvents(first: 500, occurredAtFrom: "2023-01-01T12:00:00.000", occurredAtTo: "2023-01-01T13:00:00.000"){
edges{
node{
type
occurredAt
actor{
name
}
subject{
name
type
}
}
}
}
}
}
Get organization audit events of a specific user
Query audit events from within an organization of a specific user. Audit events are only available to Enterprise customers.
query getActorRefinedOrganizationAuditEvents{
organization(slug:"organization-slug"){
auditEvents(first: 500, actor: "user-id"){
edges{
node{
type
occurredAt
actor{
name
}
subject{
name
type
}
}
}
}
}
}
To find the actor's user-id for the query above, the following query can be run: replacing the search term with the name/email of the user:
query getActorID{
organization(slug:"organization-slug"){
members(first:50, search: "search term"){
edges{
node{
user{
name
email
id
}
}
}
}
}
}