Canonical

Canonical Groups Service API

The GroupsService API from Canonical — 8 operation(s) for groupsservice.

GitHub OpenAPI

Operations 14

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /api/v0/groups List identity platform groups · Groups service list groups #
Ask an LLM
“What groups exist in the identity platform admin?”
“Can I see every group defined for access control?”
Tell an agent
List all groups.
Show me every group in the identity platform.
POST /api/v0/groups Create a group · Groups service create group #
Ask an LLM
“How do I add a new group in the identity admin?”
“Can I choose the ID when creating a group?”
Tell an agent
Create a group called {name}.
Add a new group {name} with ID {id}.
DELETE /api/v0/groups/{id} Delete a group · Groups service remove group #
Ask an LLM
“How do I delete a group I no longer need?”
“Can I remove a whole group from the identity platform?”
Tell an agent destructive · confirm first
Delete group {id}.
Remove the group {id} entirely.
GET /api/v0/groups/{id} Get a group · Groups service get group #
Ask an LLM
“What are the details of a particular group?”
“Can I fetch a single group by its ID?”
Tell an agent
Show group {id}.
Look up the group with ID {id}.
PATCH /api/v0/groups/{id} Rename or update a group · Groups service update group #
Ask an LLM
“Can I rename an existing group?”
“How would I change a group's details after creating it?”
Tell an agent
Rename group {id} to {name}.
Update the name on group {id}.
GET /api/v0/groups/{id}/entitlements List a group's entitlements · Groups service list group entitlements #
Ask an LLM
“What entitlements has a group been granted?”
“Can I page through a group's entitlements with a pagination token?”
Tell an agent
List the entitlements of group {id}.
Show the next page of entitlements for group {id} using token {X-Token-Pagination}.
PATCH /api/v0/groups/{id}/entitlements Grant or change a group's entitlements · Groups service update group entitlements #
Ask an LLM
“How do I give a group new entitlements?”
“Can I add several entitlements to a group in one call?”
Tell an agent
Apply entitlement updates {updates} to group {id}.
Grant group {id} the entitlements in {updates}.
DELETE /api/v0/groups/{id}/entitlements/{entitlementId} Remove one entitlement from a group · Groups service remove group entitlement #
Ask an LLM
“How do I revoke a single entitlement from a group?”
“Can I take away one permission from a group without touching the others?”
Tell an agent destructive · confirm first
Remove entitlement {entitlementId} from group {id}.
Revoke group {id}'s entitlement {entitlementId}.
GET /api/v0/groups/{id}/identities List the members of a group · Groups service get group identities #
Ask an LLM
“Which users and identities belong to a group?”
“Who is a member of a specific group?”
Tell an agent
List the identities in group {id}.
Show me who belongs to group {id}.
PATCH /api/v0/groups/{id}/identities Add identities to a group · Groups service update group identities #
Ask an LLM
“How do I add users to a group?”
“Can I put several identities into a group at once?”
Tell an agent
Add identities {identities} to group {id}.
Update group {id}'s membership with {identities}.
DELETE /api/v0/groups/{id}/identities/{identityId} Remove a member from a group · Groups service remove group identity #
Ask an LLM
“How do I take a user out of a group?”
“Can I remove one identity from a group's membership?”
Tell an agent destructive · confirm first
Remove identity {identityId} from group {id}.
Kick member {identityId} out of group {id}.
GET /api/v0/groups/{id}/roles List a group's roles · Groups service get group roles #
Ask an LLM
“Which roles are assigned to a group?”
“What roles does a particular group carry?”
Tell an agent
List the roles assigned to group {id}.
Show group {id}'s roles.
POST /api/v0/groups/{id}/roles Assign roles to a group · Groups service update group roles #
Ask an LLM
“How do I assign roles to a group?”
“Can I give a group several roles in one request?”
Tell an agent
Assign roles {roles} to group {id}.
Give group {id} the roles {roles}.
DELETE /api/v0/groups/{id}/roles/{roleId} Remove a role from a group · Groups service remove group role #
Ask an LLM
“How do I unassign a role from a group?”
“Can I strip one role off a group and keep its others?”
Tell an agent destructive · confirm first
Remove role {roleId} from group {id}.
Unassign role {roleId} from group {id}.

Documentation

📖
Documentation
https://snapcraft.io/docs/reference/development/snapd-rest-api/
📖
Documentation
https://ubuntu.com/landscape/docs
📖
APIReference
https://documentation.ubuntu.com/landscape/reference/api/
📖
Documentation
https://documentation.ubuntu.com/lxd/latest/rest-api/
📖
APIReference
https://documentation.ubuntu.com/lxd/latest/api-extensions/
📖
Documentation
https://ubuntu.com/security/api/docs
📖
APIReference
https://ubuntu.com/security/api/spec.json
📖
Documentation
https://documentation.ubuntu.com/pebble/
📖
Documentation
https://canonical-testflinger.readthedocs-hosted.com/en/latest/
📖
Documentation
https://documentation.ubuntu.com/anbox-cloud/

Specifications

⚙
OpenAPI
https://artifacts.apis.io/canonical/openapi/canonical-groupsservice-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/canonical/json-schema/canonical-apigroups-create-group-resp-schema.json
📊
JSONSchema
https://artifacts.apis.io/canonical/json-schema/canonical-apigroups-get-group-resp-schema.json
📊
JSONSchema
https://artifacts.apis.io/canonical/json-schema/canonical-apigroups-list-groups-resp-schema.json
📊
JSONSchema
https://artifacts.apis.io/canonical/json-schema/canonical-groups-get-group-identities-resp-schema.json

Other Resources

🔗
HowTo
https://snapcraft.io/docs/how-to-guides/snap-development/use-the-rest-api/
🔗
ReleaseNotes
https://documentation.ubuntu.com/landscape/reference/release-notes/
🔗
Portal
https://ubuntu.com/landscape
🔗
SourceCode
https://github.com/canonical/lxd
🔗
Portal
https://canonical.com/lxd
🔗
Portal
https://ubuntu.com/security
🔗
SourceCode
https://github.com/canonical/pebble
🔗
SourceCode
https://github.com/canonical/testflinger
🔗
SourceCode
https://github.com/canonical/hardware-api
🔗
Portal
https://ubuntu.com/certified
🔗
SourceCode
https://github.com/canonical/identity-platform-api
🔗
SourceCode
https://github.com/canonical/test_observer
🔗
Portal
https://canonical.com/anbox-cloud
🔗
SourceCode
https://github.com/canonical/cos-registration-server

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/canonical:canonical-groupsservice-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

canonical-groupsservice-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  contact:
    name: Identity Platform API
    url: https://github.com/canonical/identity-platform-api
  description: REST API for the Admin UI service
  license:
    name: AGPL-3.0
    url: https://github.com/canonical/identity-platform-api/blob/main/LICENSE
  title: Identity Platform Groups Service API
  version: '0.1'
tags:
- name: GroupsService
paths:
  /api/v0/groups:
    get:
      operationId: GroupsService_ListGroups
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apigroupsListGroupsResp'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service list groups
      x-summary-source: derived
    post:
      operationId: GroupsService_CreateGroup
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apigroupsGroup'
        required: true
        x-originalParamName: group
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apigroupsCreateGroupResp'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service create group
      x-summary-source: derived
  /api/v0/groups/{id}:
    delete:
      operationId: GroupsService_RemoveGroup
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apigroupsRemoveGroupResp'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service remove group
      x-summary-source: derived
    get:
      operationId: GroupsService_GetGroup
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/apigroupsGetGroupResp'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service get group
      x-summary-source: derived
    patch:
      operationId: GroupsService_UpdateGroup
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/apigroupsGroup'
        required: true
        x-originalParamName: group
      responses:
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        '501':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Not implemented
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service update group
      x-summary-source: derived
  /api/v0/groups/{id}/entitlements:
    get:
      operationId: GroupsService_ListGroupEntitlements
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - description: Base64 encoded pagination info
        in: header
        name: X-Token-Pagination
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupsListGroupEntitlementsResp'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service list group entitlements
      x-summary-source: derived
    patch:
      operationId: GroupsService_UpdateGroupEntitlements
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/typesPermissions'
        required: true
        x-originalParamName: entitlementsPatchReq
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupsUpdateGroupEntitlementsResp'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service update group entitlements
      x-summary-source: derived
  /api/v0/groups/{id}/entitlements/{entitlementId}:
    delete:
      operationId: GroupsService_RemoveGroupEntitlement
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - in: path
        name: entitlementId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupsRemoveGroupEntitlementResp'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service remove group entitlement
      x-summary-source: derived
  /api/v0/groups/{id}/identities:
    get:
      operationId: GroupsService_GetGroupIdentities
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupsGetGroupIdentitiesResp'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service get group identities
      x-summary-source: derived
    patch:
      operationId: GroupsService_UpdateGroupIdentities
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/groupsIdentities'
        required: true
        x-originalParamName: identities
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupsUpdateGroupIdentitiesResp'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service update group identities
      x-summary-source: derived
  /api/v0/groups/{id}/identities/{identityId}:
    delete:
      operationId: GroupsService_RemoveGroupIdentity
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - in: path
        name: identityId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupsRemoveGroupIdentityResp'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service remove group identity
      x-summary-source: derived
  /api/v0/groups/{id}/roles:
    get:
      operationId: GroupsService_GetGroupRoles
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupsGetGroupRolesResp'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service get group roles
      x-summary-source: derived
    post:
      operationId: GroupsService_UpdateGroupRoles
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/groupsRoles'
        required: true
        x-originalParamName: roles
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupsUpdateGroupRolesResp'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service update group roles
      x-summary-source: derived
  /api/v0/groups/{id}/roles/{roleId}:
    delete:
      operationId: GroupsService_RemoveGroupRole
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
      - in: path
        name: roleId
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/groupsRemoveGroupRoleResp'
          description: ''
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Forbidden
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - GroupsService
      summary: Groups service remove group role
      x-summary-source: derived
components:
  schemas:
    groupsRoles:
      properties:
        roles:
          items:
            type: string
          type: array
      type: object
    groupsListGroupEntitlementsResp:
      properties:
        data:
          items:
            type: string
          type: array
        message:
          type: string
        status:
          format: int32
          type: integer
      type: object
    groupsRemoveGroupEntitlementResp:
      properties:
        message:
          type: string
        status:
          format: int32
          type: integer
      type: object
    typesPagination:
      properties:
        next:
          type: string
        pageToken:
          type: string
        prev:
          type: string
        size:
          format: int32
          type: integer
      type: object
    apigroupsListGroupsResp:
      properties:
        data:
          items:
            type: string
          type: array
        message:
          type: string
        meta:
          $ref: '#/components/schemas/typesPagination'
        status:
          format: int32
          type: integer
      type: object
    groupsUpdateGroupRolesResp:
      properties:
        message:
          type: string
        status:
          format: int32
          type: integer
      type: object
    groupsRemoveGroupRoleResp:
      properties:
        message:
          type: string
        status:
          format: int32
          type: integer
      type: object
    apigroupsRemoveGroupResp:
      properties:
        message:
          type: string
        status:
          format: int32
          type: integer
      type: object
    groupsGetGroupRolesResp:
      properties:
        data:
          items:
            type: string
          type: array
        message:
          type: string
        meta:
          $ref: '#/components/schemas/typesPagination'
        status:
          format: int32
          type: integer
      type: object
    groupsIdentities:
      properties:
        identities:
          items:
            type: string
          type: array
      type: object
    apigroupsGroup:
      properties:
        id:
          type: string
        name:
          type: string
      type: object
    groupsUpdateGroupIdentitiesResp:
      properties:
        message:
          type: string
        status:
          format: int32
          type: integer
      type: object
    typesPermission:
      properties:
        object:
          type: string
        relation:
          type: string
      type: object
    groupsRemoveGroupIdentityResp:
      properties:
        message:
          type: string
        status:
          format: int32
          type: integer
      type: object
    apigroupsGetGroupResp:
      properties:
        data:
          items:
            $ref: '#/components/schemas/apigroupsGroup'
          type: array
        message:
          type: string
        meta:
          $ref: '#/components/schemas/typesPagination'
        status:
          format: int32
          type: integer
      type: object
    groupsUpdateGroupEntitlementsResp:
      properties:
        message:
          type: string
        status:
          format: int32
          type: integer
      type: object
    apigroupsCreateGroupResp:
      properties:
        data:
          items:
            $ref: '#/components/schemas/apigroupsGroup'
          type: array
        message:
          type: string
        meta:
          $ref: '#/components/schemas/typesPagination'
        status:
          format: int32
          type: integer
      type: object
    typesErrorResponse:
      properties:
        message:
          type: string
        status:
          format: int32
          type: integer
      type: object
    groupsGetGroupIdentitiesResp:
      properties:
        data:
          items:
            type: string
          type: array
        message:
          type: string
        meta:
          $ref: '#/components/schemas/typesPagination'
        status:
          format: int32
          type: integer
      type: object
    typesPermissions:
      properties:
        updates:
          items:
            $ref: '#/components/schemas/typesPermission'
          type: array
      type: object
  securitySchemes:
    OAuth2:
      flows:
        authorizationCode:
          authorizationUrl: https://example.com/oauth/authorize
          scopes:
            email: ''
            openid: ''
            profile: ''
          tokenUrl: https://example.com/oauth/token
      type: oauth2
externalDocs:
  description: REST API for the Admin UI service
  url: https://github.com/canonical/identity-platform-admin-ui/blob/main/API.md