openapi: 3.2.0 info: title: Cloud Foundry V3 Roles API description: '# Welcome to the Experimental Cloud Foundry V3 API Docs!' version: latest license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html contact: name: Cloud Foundry url: https://www.cloudfoundry.org/ servers: - url: https://api.example.local description: Cloud Foundry V3 API server security: - oauth: - cloud_controller.read - cloud_controller.write tags: - name: Roles description: Roles are used to control access to resources. paths: /v3/roles: get: summary: List roles description: This endpoint lists roles that the user has access to. operationId: listRoles tags: - Roles parameters: - $ref: '#/components/parameters/Page' - $ref: '#/components/parameters/PerPage' - $ref: '#/components/parameters/OrderBy' - $ref: '#/components/parameters/CreatedAts' - $ref: '#/components/parameters/UpdatedAts' - $ref: '#/components/parameters/LabelSelector' - name: guids in: query description: Comma-delimited list of role guids to filter by schema: type: array items: type: string - name: types in: query description: Comma-delimited list of role types to filter by schema: type: array items: type: string enum: - organization_user - organization_auditor - organization_manager - organization_billing_manager - space_auditor - space_developer - space_manager - space_supporter - name: organization_guids in: query description: Comma-delimited list of organization guids to filter by schema: type: array items: type: string - name: space_guids in: query description: Comma-delimited list of space guids to filter by schema: type: array items: type: string - name: user_guids in: query description: Comma-delimited list of user guids to filter by schema: type: array items: type: string - name: include in: query description: Optionally include additional related resources in the response; valid values are `user`, `space`, and `organization`. schema: type: array items: type: string enum: - user - space - organization responses: '200': $ref: '#/components/responses/RoleListResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' post: summary: Create a role description: 'This endpoint creates a new role for a user in an organization or space. To create an organization role you must be an admin or organization manager in the organization associated with the role. To create a space role you must be an admin, an organization manager in the parent organization of the space associated with the role, or a space manager in the space associated with the role. For a user to be assigned a space role, the user must already have an organization role in the parent organization. If the associated user is valid but does not exist in Cloud Controller’s database, a user resource will be created automatically. If CAPI property `cc.allow_user_creation_by_org_manager` is enabled, the organization role is being created by username + origin and the user does not exist in UAA yet, the user will be created. The origin must be different from `uaa` in this case.' operationId: createRole tags: - Roles requestBody: $ref: '#/components/requestBodies/RoleCreate' responses: '201': description: Role created content: application/json: schema: $ref: '#/components/schemas/Role' examples: by_user_guid: summary: by user guid value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2019-10-10T17:19:12Z' updated_at: '2019-10-10T17:19:12Z' type: organization_auditor relationships: user: data: guid: 123e4567-e89b-12d3-a456-426614174000 user_group: data: null organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 space: data: null links: self: href: https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418 user: href: https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8 organization: href: https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c by_username_and_origin: summary: by username and origin value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2019-10-10T17:19:12Z' updated_at: '2019-10-10T17:19:12Z' type: organization_auditor relationships: user: data: guid: 123e4567-e89b-12d3-a456-426614174000 user_group: data: null organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 space: data: null links: self: href: https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418 user: href: https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8 organization: href: https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c links: user: operationId: getUser parameters: guid: $response.body#/relationships/user/data/guid description: Retrieve the user for this role organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this role (if organization role) space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this role (if space role) '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/500' '503': $ref: '#/components/responses/ServiceUnavailable' /v3/roles/{guid}: get: summary: Get a role description: This endpoint gets an individual role resource. operationId: getRole tags: - Roles parameters: - $ref: '#/components/parameters/Guid' - name: include in: query description: Optionally include additional related resources in the response; valid values are `user`, `space`, and `organization`. schema: type: array items: type: string enum: - user - space - organization responses: '200': description: Role retrieved content: application/json: schema: $ref: '#/components/schemas/Role' examples: default: summary: default value: guid: 123e4567-e89b-12d3-a456-426614174000 created_at: '2019-10-10T17:19:12Z' updated_at: '2019-10-10T17:19:12Z' type: organization_auditor relationships: user: data: guid: 123e4567-e89b-12d3-a456-426614174000 user_group: data: null organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 space: data: null links: self: href: https://api.example.org/v3/roles/40557c70-d1bd-4976-a2ab-a85f5e882418 user: href: https://api.example.org/v3/users/59eadb5f-fc13-414f-84ba-77a35e239cc8 organization: href: https://api.example.org/v3/organizations/05c5da3b-6cbc-421c-87c3-20bb3c41ab7c links: user: operationId: getUser parameters: guid: $response.body#/relationships/user/data/guid description: Retrieve the user for this role organization: operationId: getOrganization parameters: guid: $response.body#/relationships/organization/data/guid description: Retrieve the organization for this role (if organization role) space: operationId: getSpace parameters: guid: $response.body#/relationships/space/data/guid description: Retrieve the space for this role (if space role) '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' delete: summary: Delete a role description: This endpoint deletes an individual role. operationId: deleteRole tags: - Roles parameters: - $ref: '#/components/parameters/Guid' responses: '202': description: Accepted headers: Location: description: URL of the job that is deleting the role schema: type: string format: uri '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/500' components: schemas: Link: type: object properties: href: type: string description: The URL of the link method: type: string description: An optional field containing the HTTP method to be used when following the URL required: - href description: 'Each link is keyed by its type and will include a href for the URL and an optional method for links that cannot be followed using GET. ' Relationship: type: object properties: guid: type: string format: uuid description: The GUID of the resource Error: type: object properties: code: type: integer description: A numeric code for this error detail: type: string description: Detailed description of the error title: type: string description: Name of the error Domain: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: The name of the domain; must be between 3 ~ 253 characters and follow [RFC 1035](https://tools.ietf.org/html/rfc1035) internal: type: boolean description: Whether the domain is used for internal (container-to-container) traffic router_group: type: - object - 'null' properties: guid: type: string format: uuid description: The guid of the desired router group to route `tcp` traffic through; if set, the domain will only be available for `tcp` traffic supported_protocols: type: array items: type: string enum: - http - tcp description: Available protocols for routes using the domain, currently `http` and `tcp` relationships: $ref: '#/components/schemas/Relationships' metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this domain organization: $ref: '#/components/schemas/Link' description: The URL to get the organization for this domain route_reservations: $ref: '#/components/schemas/Link' description: The URL to get the route reservations for this domain shared_organizations: $ref: '#/components/schemas/Link' description: The URL to get the shared organizations for this domain router_group: $ref: '#/components/schemas/Link' description: The URL to get the router group for this domain description: 'A domain is a fully qualified domain name that is used for application routes. A domain can be scoped to an organization, meaning it can be used to create routes for spaces inside that organization, or be left unscoped to allow all organizations access. ' App: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: The name of the app state: type: string description: Current desired state of the app enum: - STOPPED - STARTED lifecycle: $ref: '#/components/schemas/Lifecycle' description: Provides the default lifecycle object for the application. This lifecycle will be used when staging and running the application. The staging lifecycle can be overridden on builds relationships: $ref: '#/components/schemas/Relationships' metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this app space: $ref: '#/components/schemas/Link' description: The URL to get the space for this app processes: $ref: '#/components/schemas/Link' description: The URL to get the processes for this app packages: $ref: '#/components/schemas/Link' description: The URL to get the packages for this app environment_variables: $ref: '#/components/schemas/Link' description: The URL to get the environment variables for this app current_droplet: $ref: '#/components/schemas/Link' description: The URL to get the current droplet for this app droplets: $ref: '#/components/schemas/Link' description: The URL to get the droplets for this app tasks: $ref: '#/components/schemas/Link' description: The URL to get the tasks for this app start: $ref: '#/components/schemas/Link' description: The URL to start the app stop: $ref: '#/components/schemas/Link' description: The URL to stop the app revisions: $ref: '#/components/schemas/Link' description: The URL to get the revisions for this app deployed_revisions: $ref: '#/components/schemas/Link' description: The URL to get the deployed revisions for this app features: $ref: '#/components/schemas/Link' description: The URL to get the features for this app included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter description: 'Apps represent the core entities in the Cloud Foundry environment. They are the deployable units that run your code. Each app can have multiple processes, routes, and services associated with it. Apps can be scaled horizontally by increasing the number of instances. They can also be updated and restarted as needed. ' Errors: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' description: 'An error response will always return a list of error objects. Errors appear on the job resource for asynchronous operations. Clients should use the code and title fields for programmatically handling specific errors. The message in the detail field is subject to change over time. ' Lifecycle: type: object properties: type: type: string description: Type of the lifecycle; valid values are buildpack, cnb, docker data: type: object additionalProperties: true description: Data specific to the lifecycle properties: buildpacks: type: array items: type: string description: List of the names of buildpacks, URLs from which they may be downloaded, or null to auto-detect a suitable buildpack during staging (applicable for buildpack and cnb lifecycles) stack: type: - string - 'null' description: The root filesystem to use with the buildpack, for example cflinuxfs4 (applicable for buildpack lifecycle) credentials: type: object additionalProperties: type: object properties: username: type: - string - 'null' password: type: - string - 'null' token: type: string description: Credentials used to download the configured buildpacks (applicable for cnb lifecycle) description: 'The lifecycle type defines how the application droplet is created and run. The following lifecycle types are supported: - buildpack: Traditional buildpacks for Cloud Foundry applications. - cnb: Cloud Native Buildpacks that are OCI-compliant. - docker: Run pre-built Docker images. ' RelationshipToOne: type: object properties: data: type: - object - 'null' $ref: '#/components/schemas/Relationship' links: type: object properties: self: $ref: '#/components/schemas/Link' related: $ref: '#/components/schemas/Link' description: 'Some relationships relate a resource to exactly one other resource. For example an app can belong to only one space. ' UserRelationshipToOne: type: - object - 'null' properties: data: type: object description: 'User relationship data that can be specified either by GUID or by username and origin. When using username and origin, the set_roles_by_username feature flag must be enabled. ' oneOf: - type: object properties: guid: type: string description: The GUID of the user, matching either a UAA user id or client id. A client id may not be a uuid. required: - guid additionalProperties: false - type: object properties: username: type: string description: The username of the user origin: type: string description: The identity provider for the user (e.g., 'ldap', 'saml'). Optional field to disambiguate the username. required: - username additionalProperties: false description: 'User relationship data that can be specified either by GUID or by username and origin. Set to null to clear the relationship. ' ServiceOffering: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: service_broker_guid: type: string service_broker_name: type: string metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this service offering service_plans: $ref: '#/components/schemas/Link' description: The URL to get the service plans for this offering service_broker: $ref: '#/components/schemas/Link' description: The URL to get the service broker for this offering Organization: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: Name of the organization suspended: type: boolean description: Whether an organization is suspended or not; non-admins will be blocked from creating, updating, or deleting resources in a suspended organization relationships: type: object properties: quota: $ref: '#/components/schemas/RelationshipToOne' description: The quota applied to the organization metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this organization domains: $ref: '#/components/schemas/Link' description: The URL to get the domains for this organization quota: $ref: '#/components/schemas/Link' description: The URL to get the quota for this organization default_domain: $ref: '#/components/schemas/Link' description: The URL to get the default domain for this organization description: 'An org is a development account that an individual or multiple collaborators can own and use. All collaborators access an org with user accounts. Collaborators in an org share a resource quota plan, applications, services availability, and custom domains. ' IncludedResources: type: object description: Additional related resources included in the response when using the include parameter properties: spaces: type: array items: $ref: '#/components/schemas/Space' description: Array of included space resources organizations: type: array items: $ref: '#/components/schemas/Organization' description: Array of included organization resources domains: type: array items: $ref: '#/components/schemas/Domain' description: Array of included domain resources service_offerings: type: array items: $ref: '#/components/schemas/ServiceOffering' description: Array of included service offering resources service_instances: type: array items: oneOf: - $ref: '#/components/schemas/ManagedServiceInstance' - $ref: '#/components/schemas/UserProvidedServiceInstance' discriminator: propertyName: type mapping: managed: '#/components/schemas/ManagedServiceInstance' user-provided: '#/components/schemas/UserProvidedServiceInstance' description: Array of included service instance resources apps: type: array items: $ref: '#/components/schemas/App' description: Array of included app resources routes: type: array items: $ref: '#/components/schemas/Route' description: Array of included route resources users: type: array items: $ref: '#/components/schemas/User' description: Array of included user resources additionalProperties: false Route: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: protocol: type: string host: type: string path: type: string port: type: - integer - 'null' url: type: string description: Fully qualified path or address where the route directs traffic relationships: $ref: '#/components/schemas/Relationships' metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this route space: $ref: '#/components/schemas/Link' description: The URL to get the space for this route domain: $ref: '#/components/schemas/Link' description: The URL to get the domain for this route destinations: $ref: '#/components/schemas/Link' description: The URL to get the destinations for this route included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter description: A route in Cloud Foundry is used to direct traffic from a URL to an application. Pagination: type: object properties: total_results: type: integer description: The total number of results available total_pages: type: integer description: The total number of pages available first: allOf: - $ref: '#/components/schemas/Link' - description: The first page of results last: allOf: - $ref: '#/components/schemas/Link' - description: The last page of results next: oneOf: - $ref: '#/components/schemas/Link' - type: 'null' description: The next page of results previous: oneOf: - $ref: '#/components/schemas/Link' - type: 'null' description: The previous page of results description: 'Pagination is a technique used to divide a large set of results into smaller, more manageable sets. This allows clients to retrieve results in smaller chunks, reducing the amount of data transferred and improving performance. The pagination object is a JSON object that contains information about the pagination state of the results. It includes the total number of results available, the total number of pages available, and links to the first, last, next, and previous pages of results. ' Space: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: name: type: string description: Name of the space relationships: type: object properties: organization: $ref: '#/components/schemas/RelationshipToOne' quota: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the space links: type: object properties: self: $ref: '#/components/schemas/Link' organization: $ref: '#/components/schemas/Link' features: $ref: '#/components/schemas/Link' apply_manifest: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter required: - name - relationships - links ManagedServiceInstance: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: type: type: string enum: - managed description: Type of service instance name: type: string description: Name of the service instance tags: type: array items: type: string description: Tags for the service instance syslog_drain_url: type: - string - 'null' format: uri description: URL for syslog drain route_service_url: type: - string - 'null' format: uri description: URL for route service dashboard_url: type: - string - 'null' format: uri description: URL for service dashboard maintenance_info: type: object properties: version: type: string description: Version of maintenance info description: type: - string - 'null' description: Description of maintenance info upgrade_available: type: boolean description: Whether an upgrade is available last_operation: $ref: '#/components/schemas/ServiceInstanceLastOperation' relationships: type: object properties: space: $ref: '#/components/schemas/RelationshipToOne' service_plan: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the service instance links: type: object properties: self: $ref: '#/components/schemas/Link' space: $ref: '#/components/schemas/Link' service_plan: $ref: '#/components/schemas/Link' parameters: $ref: '#/components/schemas/Link' service_credential_bindings: $ref: '#/components/schemas/Link' service_route_bindings: $ref: '#/components/schemas/Link' shared_spaces: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' required: - type - name - relationships - links UserProvidedServiceInstance: type: object allOf: - $ref: '#/components/schemas/BaseSchema' - properties: type: type: string enum: - user-provided description: Type of service instance name: type: string description: Name of the service instance tags: type: array items: type: string description: Tags for the service instance syslog_drain_url: type: - string - 'null' format: uri description: URL for syslog drain route_service_url: type: - string - 'null' format: uri description: URL for route service relationships: type: object properties: space: $ref: '#/components/schemas/RelationshipToOne' description: Relationships for the service instance links: type: object properties: self: $ref: '#/components/schemas/Link' space: $ref: '#/components/schemas/Link' service_credential_bindings: $ref: '#/components/schemas/Link' service_route_bindings: $ref: '#/components/schemas/Link' credentials: $ref: '#/components/schemas/Link' metadata: $ref: '#/components/schemas/Metadata' required: - type - name - relationships - links ServiceInstanceLastOperation: type: object properties: type: type: string description: Type of the last operation enum: - create - update - delete state: type: string description: State of the last operation enum: - initial - in progress - succeeded - failed description: type: - string - 'null' description: A textual explanation associated with this state created_at: type: string format: date-time description: When the last operation was created updated_at: type: string format: date-time description: When the last operation was last updated description: The last operation object for service instances Metadata: type: object properties: labels: type: object additionalProperties: type: - string - 'null' description: 'A set of key-value pairs that describe the resource. Labels are a JSON object that contains information about a resource. They are used to tag resources with metadata that can be used to filter and group resources. Labels are included in the response body of a request to retrieve a resource. Labels are user-specified key/value pairs that are attached to API Resources. They are queryable, identifying attributes of a resource, but they do not affect the operation of CloudFoundry. For example, an app may be assigned a label with key sensitive and possible values true or false. Users could then find all sensitive apps with a selector for sensitive=true, resulting in a response containing only apps having the label key sensitive with a label value of true. Labels Labels allow users to apply identifying attributes to resources that are meaningful to the user, but not the CloudFoundry system. Examples may include (but are not limited to): "production" : "true" or "production" : "false" "env" : "dev" or "env" : "test" or "env" : "prod" "chargeback-code" : "abc123" Label keys Label keys are made up of an (optional) prefix, and name. If a prefix is present, it is separated from the name by a /. Prefixes are dns names intended to enable namespacing of label keys. A label key prefix must adhere to the following restrictions: Length: 0-253 characters Allowed characters: alphanumeric ( [a-z0-9A-Z] ), -, and . DNS subdomain format (series of subdomain labels separated by .) A label key name must adhere to the following restrictions: Length: 1-63 characters Allowed characters: alphanumeric ( [a-z0-9A-Z] ), -, _, and . Must begin and end with an alphanumeric character Label values Label values must adhere to the following restrictions: Length: 0-63 characters Allowed characters: alphanumeric ( [a-z0-9A-Z] ), -, _, and . Must begin and end with an alphanumeric character Empty values are allowed ' annotations: type: object additionalProperties: type: - string - 'null' description: 'A set of key-value pairs that describe the resource. Annotations are a JSON object that contains information about a resource. They are used to tag resources with metadata that can be used to filter and group resources. Annotations are included in the response body of a request to retrieve a resource. Annotations are user-specified key-value pairs that are attached to API resources. They do not affect the operation of Cloud Foundry. Annotations cannot be used in filters. When a service instance is being created, the service broker is sent the annotations of the service instance, and the space and organization in which the service instance resides. When a service instance is being updated, the service broker is sent the annotations of the space and organization in which the service instance resides. When a service binding is being created, the service broker is sent annotations of any associated app, and the space and organization in which the binding resides. Only annotations with a prefix (e.g. company.com/contacts) are sent to service brokers. Examples may include (but are not limited to): "contact info": "bob@example.com jane@example.com" "library versions": "Spring: 5.1, Redis Client: a184098. yaml parser: 38" "git-sha": "d56fe0367554ae5e878e37ed6c5b9a82f5995512" Annotation keys Annotation keys are made up of an (optional) prefix and name. If a prefix is present, it is separated from the name by a /. Prefixes are DNS names intended to enable namespacing of annotation keys. An annotation key prefix must adhere to the following restrictions: Length: 0-253 characters Allowed characters: a-z, A-Z, 0-9, -, and .; emojis cannot be used in keys DNS subdomain format (series of subdomain annotations separated by .) An annotation key name must adhere to the following restrictions: Length: 1-63 characters Allowed characters: a-z, A-Z, 0-9, -, _, and .; emojis cannot be used in keys Must begin and end with an alphanumeric character Annotation values Annotation values must adhere to the following restrictions: Length: 0-5000 unicode characters ' description: 'Metadata is a JSON object that contains information about a resource. It includes the GUID of the resource, the time the resource was created, the time the resource was last updated, and links to the resource. Metadata is included in the response body of a request to retrieve a resource. ' Role: allOf: - $ref: '#/components/schemas/BaseSchema' type: object properties: type: type: string description: 'Role type. Possible values are: - `organization_user`: A user in the organization - `organization_auditor`: An auditor in the organization - `organization_manager`: A manager in the organization - `organization_billing_manager`: A billing manager in the organization - `space_auditor`: An auditor in the space - `space_developer`: A developer in the space - `space_manager`: A manager in the space - `space_supporter`: A supporter in the space (not authorized to use the V2 API)' enum: - organization_user - organization_auditor - organization_manager - organization_billing_manager - space_auditor - space_developer - space_manager - space_supporter relationships: allOf: - $ref: '#/components/schemas/Relationships' properties: organization: allOf: - $ref: '#/components/schemas/RelationshipToOne' - description: 'A relationship to the organization the role controls access to; when this is a space role, `organization.data` will be `null`. ' space: allOf: - $ref: '#/components/schemas/RelationshipToOne' - description: 'A relationship to the space the role controls access to; when this is an organization role, `space.data` will be `null`. ' user: allOf: - $ref: '#/components/schemas/UserRelationshipToOne' - description: 'A relationship to the user; this is the user that has the role ' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this role user: $ref: '#/components/schemas/Link' description: The URL to get the user for this role organization: $ref: '#/components/schemas/Link' description: The URL to get the organization for this role space: $ref: '#/components/schemas/Link' description: The URL to get the space for this role included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter description: 'Roles represent a set of permissions that can be granted to users. Roles are represented as a JSON object. A role consists of several required role fields and other attributes specific to the role. See Roles for specific roles. ' User: type: object properties: guid: type: string description: Unique identifier for the user, matching either a UAA user id or client id. A client id may not be a uuid. created_at: type: string format: date-time description: The ISO8601 compatible date and time when resource was created updated_at: type: string format: date-time description: The ISO8601 compatible date and time when resource was last updated username: type: - string - 'null' description: The username of the user presentation_name: type: string description: The presentation name of the user origin: type: - string - 'null' description: The origin of the user metadata: $ref: '#/components/schemas/Metadata' links: type: object properties: self: $ref: '#/components/schemas/Link' description: The URL to get this user BaseSchema: type: object properties: guid: type: string format: uuid description: The unique identifier for the resource created_at: type: string format: date-time description: The ISO8601 compatible date and time when resource was created updated_at: type: string format: date-time description: The ISO8601 compatible date and time when resource was last updated description: 'A resource represents an individual object within the system, such as an app or a service. It is represented as a JSON object. A resource consists of several required resource fields and other attributes specific to the resource. See Resources and Experimental Resources for specific resources. ' Relationships: type: object description: 'Relationships represent associations between resources. When relationships are mutable, they can be used to create, read, update, and delete these associations. An app’s relationship to its current droplet is mutable, but an app’s relationship to its space is not. Relationships do not affect the fundamental properties of a resource, but may affect their behavior and permissions logic. Relationships are tied to the lifecycles of the associated resources and will be removed if either of the associated resources are deleted. For example, if a user is removed from an organization, both the user and the organization persist, but the relationship between them does not. Not all resources implement every relationship operation demonstrated in the examples below. See the docs for each resource to see how it interacts with its relationships. Endpoints that return relationship data list this information under the relationships key. The relationship object The relationship object is a key-value pair that uniquely identifies a resource. In practice this is almost always the guid of a resource. ' responses: Forbidden: description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Errors' NotFound: description: Not Found content: application/json: schema: $ref: '#/components/schemas/Errors' UnprocessableEntity: description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Errors' BadGateway: description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/Error' BadRequest: description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Errors' text/html: schema: type: string RoleListResponse: description: Roles retrieved content: application/json: schema: type: object properties: pagination: $ref: '#/components/schemas/Pagination' resources: type: array items: $ref: '#/components/schemas/Role' included: $ref: '#/components/schemas/IncludedResources' description: Additional related resources included in the response when using the include parameter Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Errors' Conflict: description: Conflict content: application/json: schema: $ref: '#/components/schemas/Errors' TooManyRequests: description: Too Many Requests content: application/json: schema: type: object properties: errors: type: array items: type: object properties: code: type: integer example: 10008 title: type: string example: CF-RateLimitExceeded detail: type: string example: Rate limit exceeded '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Errors' ServiceUnavailable: description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/Errors' parameters: OrderBy: name: order_by in: query required: false schema: type: string description: 'Value to sort by. Defaults to ascending; prepend with `-` to sort descending. ' example: created_at Guid: name: guid in: path required: true schema: type: string format: uuid description: The unique identifier for the resource PerPage: name: per_page in: query required: false schema: type: integer description: Number of results per page, valid values are 1 through 5000 example: 50 Page: name: page in: query required: false schema: type: integer description: Page to display; valid values are integers >= 1 example: 1 UpdatedAts: name: updated_ats in: query required: false schema: type: string description: 'Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators). ' example: '2021-01-01T00:00:00Z' LabelSelector: name: label_selector in: query description: A query string containing a list of [label selector](#labels-and-selectors) requirements required: false schema: type: string example: environment=production CreatedAts: name: created_ats in: query required: false schema: type: string description: 'Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators). ' example: '2021-01-01T00:00:00Z' requestBodies: RoleCreate: description: Role to create content: application/json: schema: type: object properties: type: type: string description: Role to create enum: - organization_user - organization_auditor - organization_manager - organization_billing_manager - space_auditor - space_developer - space_manager - space_supporter relationships: type: object properties: user: $ref: '#/components/schemas/UserRelationshipToOne' organization: $ref: '#/components/schemas/RelationshipToOne' description: A relationship to an organization; required only when creating an organization role space: $ref: '#/components/schemas/RelationshipToOne' description: A relationship to a space; required only when creating a space role examples: by_user_guid: summary: by user guid value: type: organization_auditor relationships: user: data: guid: 123e4567-e89b-12d3-a456-426614174000 organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 by_username_and_origin: summary: by username and origin value: type: organization_auditor relationships: user: data: username: user-name origin: ldap organization: data: guid: 123e4567-e89b-12d3-a456-426614174000 securitySchemes: oauth: type: oauth2 flows: implicit: authorizationUrl: https://uaa.cloudfoundry.local/api-oauth/dialog scopes: cloud_controller.admin: This scope provides read and write access to all resources cloud_controller.admin_read_only: This scope provides read only access to all resources cloud_controller.global_auditor: This scope provides read access to all resources cloud_controller.read: Read access to the Cloud Controller cloud_controller.write: Write access to the Cloud Controller cloud_controller.update_build_state: This scope allows its bearer to update the state of a build; currently only used when updating builds cloud_controller_service_permissions.read: This scope provides read only access for service instance permissions bearer: type: http scheme: bearer bearerFormat: JWT description: Bearer JWT token authentication