Pulumi Services API
The Services API from Pulumi — 4 operation(s) for services.
OpenAPI Specification
openapi: 3.0.3
info:
description: APIs and Definitions for the Pulumi Cloud product.
title: Pulumi APIs AccessTokens Services API
version: 1.0.0
tags:
- name: Services
paths:
/api/orgs/{orgName}/services:
get:
description: Returns all service accounts in an organization. Service accounts provide programmatic, non-human identities for accessing Pulumi Cloud resources. They can hold access tokens, belong to teams, and have stack permissions, making them suitable for CI/CD pipelines, automation tools, and other machine-to-machine integrations.
operationId: ListServices
parameters:
- description: The organization name
in: path
name: orgName
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ListServicesResponse'
description: OK
summary: ListServices
tags:
- Services
post:
description: Creates a new service account in an organization. Service accounts provide programmatic, non-human identities for accessing Pulumi Cloud resources. They are scoped to an organization and can hold access tokens, belong to teams, and have stack permissions. The service name must be unique within the organization.
operationId: CreateService
parameters:
- description: The organization name
in: path
name: orgName
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateServiceRequest'
x-originalParamName: body
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Service'
description: OK
'400':
description: Invalid service data provided
'404':
description: service
'409':
description: Service with this name already exists
summary: CreateService
tags:
- Services
/api/orgs/{orgName}/services/{ownerType}/{ownerName}/{serviceName}:
delete:
description: Deletes a service account from an organization. Service accounts provide programmatic, non-human access to Pulumi Cloud resources. If the service has other members, deletion requires explicit confirmation via the force parameter. All access tokens and permissions associated with the service are revoked.
operationId: DeleteService
parameters:
- description: The organization name
in: path
name: orgName
required: true
schema:
type: string
- description: The owner type
in: path
name: ownerType
required: true
schema:
type: string
- description: The owner name
in: path
name: ownerName
required: true
schema:
type: string
- description: The service name
in: path
name: serviceName
required: true
schema:
type: string
- description: Force deletion even if the service has other members
in: query
name: force
schema:
type: boolean
responses:
'204':
description: No Content
'400':
description: invalid query parameter
'404':
description: service
'412':
description: confirmation is required to delete service with other members
summary: DeleteService
tags:
- Services
get:
description: Returns the details of a specific service account, including its name, owner, description, team memberships, access tokens, and stack permissions. Service accounts provide programmatic, non-human access to Pulumi Cloud resources and are identified by their owner type, owner name, and service name.
operationId: GetService
parameters:
- description: The organization name
in: path
name: orgName
required: true
schema:
type: string
- description: The owner type
in: path
name: ownerType
required: true
schema:
type: string
- description: The owner name
in: path
name: ownerName
required: true
schema:
type: string
- description: The service name
in: path
name: serviceName
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetServiceResponse'
description: OK
summary: GetService
tags:
- Services
head:
description: Checks whether a service account exists in the organization without returning its full details. Returns 204 No Content if the service exists, or an error if not found. This is a lightweight check useful for validating service account references.
operationId: HeadService
parameters:
- description: The organization name
in: path
name: orgName
required: true
schema:
type: string
- description: The owner type
in: path
name: ownerType
required: true
schema:
type: string
- description: The owner name
in: path
name: ownerName
required: true
schema:
type: string
- description: The service name
in: path
name: serviceName
required: true
schema:
type: string
responses:
'204':
description: No Content
summary: HeadService
tags:
- Services
patch:
description: Updates the metadata and configuration of an existing service account, such as its description, team memberships, and access settings. Service accounts provide programmatic, non-human access to Pulumi Cloud resources.
operationId: UpdateService
parameters:
- description: The organization name
in: path
name: orgName
required: true
schema:
type: string
- description: The owner type
in: path
name: ownerType
required: true
schema:
type: string
- description: The owner name
in: path
name: ownerName
required: true
schema:
type: string
- description: The service name
in: path
name: serviceName
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateServiceMetadataRequest'
x-originalParamName: body
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Service'
description: OK
'400':
description: Invalid service update data provided or invalid member type.
'404':
description: service
summary: UpdateService
tags:
- Services
/api/orgs/{orgName}/services/{ownerType}/{ownerName}/{serviceName}/items:
post:
description: Adds items (such as access tokens, team memberships, or stack permissions) to an existing service account. Service accounts provide programmatic, non-human access to Pulumi Cloud resources and are scoped to an organization. Items define what the service account can access and what credentials it holds. Returns the updated service details.
operationId: AddServiceItems
parameters:
- description: The organization name
in: path
name: orgName
required: true
schema:
type: string
- description: The owner type
in: path
name: ownerType
required: true
schema:
type: string
- description: The owner name
in: path
name: ownerName
required: true
schema:
type: string
- description: The service name
in: path
name: serviceName
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AddServiceItemsRequest'
x-originalParamName: body
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetServiceResponse'
description: OK
'400':
description: Invalid service item data provided.
summary: AddServiceItems
tags:
- Services
/api/orgs/{orgName}/services/{ownerType}/{ownerName}/{serviceName}/items/{itemType}/{itemName}:
delete:
description: Removes a specific item (such as a team membership, access token, or stack permission) from a service account. Returns the updated service details after the item has been removed.
operationId: RemoveServiceItem
parameters:
- description: The organization name
in: path
name: orgName
required: true
schema:
type: string
- description: The owner type
in: path
name: ownerType
required: true
schema:
type: string
- description: The owner name
in: path
name: ownerName
required: true
schema:
type: string
- description: The service name
in: path
name: serviceName
required: true
schema:
type: string
- description: The item type
in: path
name: itemType
required: true
schema:
type: string
- description: The item name
in: path
name: itemName
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetServiceResponse'
description: OK
'400':
description: invalid item name
summary: RemoveServiceItem
tags:
- Services
components:
schemas:
AddServiceItem:
description: A simple struct representing the metadata needed to add an item via user-facing information.
properties:
name:
description: the name (including any namespacing) of the item
type: string
x-order: 2
type:
description: the type of the item to add
type: string
x-order: 1
required:
- name
- type
type: object
ListServicesResponse:
description: Response when listing services for a user.
properties:
continuationToken:
description: 'ContinuationToken is an opaque value the client can send to fetch additional
services. Will be nil once all services have been returned.'
type: string
x-order: 2
services:
description: The list of services
items:
$ref: '#/components/schemas/Service'
type: array
x-order: 1
required:
- services
type: object
UpdateServiceMetadataRequest:
description: Request for updating a services metadata.
properties:
description:
description: an optional description of the service
type: string
x-order: 2
name:
description: the name of the service
type: string
x-order: 1
properties:
description: an optional list of properties to set on the service
items:
$ref: '#/components/schemas/ServiceProperty'
type: array
x-order: 3
type: object
GetServiceResponse:
description: Response when requesting a service.
properties:
continuationToken:
description: 'ContinuationToken is an opaque value the client can send to fetch additional
items. Will be nil once all items have been returned.'
type: string
x-order: 3
items:
description: The list of service items
items:
$ref: '#/components/schemas/ServiceItem'
type: array
x-order: 2
service:
$ref: '#/components/schemas/Service'
description: The service details
x-order: 1
required:
- items
- service
type: object
ServiceMember:
description: 'A service member is either a direct user or a indirect user representation
that allows them to access and mutate a service.'
properties:
avatarUrl:
description: an optional avatar URL for the member
type: string
x-order: 3
name:
description: the login name of the member within Pulumi
type: string
x-order: 2
type:
description: the type of the member (e.g. team / user)
type: string
x-order: 1
required:
- avatarUrl
- name
- type
type: object
ServiceItemUpdate:
description: An update that the item may have in it's history.
properties:
message:
description: the message to show alongside the timestamp
type: string
x-order: 2
success:
description: used to toggle a status icon for the update
type: boolean
x-order: 3
timestamp:
description: the timestamp of the last update
format: date-time
type: string
x-order: 1
required:
- message
- timestamp
type: object
CreateServiceRequest:
description: 'Request for creating a new service with an optional list
of items to populate the service with after creation.'
properties:
description:
description: an optional description of the service
type: string
x-order: 4
items:
description: an optional list of items to add during service creation
items:
$ref: '#/components/schemas/AddServiceItem'
type: array
x-order: 5
name:
description: the name of the service
type: string
x-order: 3
ownerName:
description: the service owner name
type: string
x-order: 2
ownerType:
description: the service owner type
type: string
x-order: 1
properties:
description: an optional list of properties to set on the service
items:
$ref: '#/components/schemas/ServiceProperty'
type: array
x-order: 6
required:
- description
- items
- name
- ownerName
- ownerType
- properties
type: object
Service:
description: 'A service is a Pulumi construct that aggregates items and additional metadata
that can be accessed by the service''s members.'
properties:
created:
description: the time the service was create
format: date-time
type: string
x-order: 5
description:
description: an optional description of the service
type: string
x-order: 4
itemCountSummary:
additionalProperties:
format: int64
type: integer
description: item types to their count within the service based on the current user's permissions
type: object
x-order: 7
members:
description: a list of members that have access to the service
items:
$ref: '#/components/schemas/ServiceMember'
type: array
x-order: 6
name:
description: the name of the service
type: string
x-order: 3
organizationName:
description: the name of the organization this service belongs to
type: string
x-order: 1
owner:
$ref: '#/components/schemas/ServiceMember'
description: the owner of the service
x-order: 2
properties:
description: an optional list of properties set on the service
items:
$ref: '#/components/schemas/ServiceProperty'
type: array
x-order: 8
required:
- description
- itemCountSummary
- members
- name
- organizationName
- owner
- properties
type: object
ServiceItem:
description: An item within a service.
properties:
addedByUser:
$ref: '#/components/schemas/ServiceMember'
description: who added the item reference to the service - this will always be a user
x-order: 7
cloudCount:
description: how many Pulumi cloud measured primitives are within this item
format: int64
type: integer
x-order: 8
created:
description: timestamp of when the item was created
format: date-time
type: string
x-order: 5
lastUpdate:
$ref: '#/components/schemas/ServiceItemUpdate'
description: when did the last update occur to this item, if any
x-order: 6
name:
description: the name (including any namespacing) of the item
type: string
x-order: 3
organizationName:
description: the name of the organization this item belongs to
type: string
x-order: 1
type:
description: the type of the item
type: string
x-order: 2
version:
description: optional field if the item has versioning
type: string
x-order: 4
required:
- cloudCount
- created
- name
- organizationName
- type
type: object
ServiceProperty:
description: A property that the service will show in it's metadata.
properties:
key:
description: the name of the property
type: string
x-order: 1
order:
description: the position of the property
format: int64
type: integer
x-order: 4
type:
description: the type of the property
type: string
x-order: 3
value:
description: the value of the property
type: string
x-order: 2
required:
- key
- order
- type
- value
type: object
AddServiceItemsRequest:
description: Request for adding items to an existing service.
properties:
items:
description: List of items
items:
$ref: '#/components/schemas/AddServiceItem'
type: array
x-order: 1
required:
- items
type: object