Canonical

Canonical Tenant Service API

The TenantService API from Canonical — 8 operation(s) for tenantservice.

GitHub OpenAPI

Operations 11

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/me/tenants List the tenants I belong to · Public Endpoints #
Ask an LLM
“Which tenants is my own account a member of?”
“Can I see only my enabled tenants?”
Tell an agent
List the tenants I belong to.
Show my tenants filtered by enabled = {enabled}.
GET /api/v0/tenants List all tenants as an admin · Internal Admin Endpoints #
Ask an LLM
“As an administrator, how do I list every tenant in the system?”
“Can I page through all tenants and filter out disabled ones?”
Tell an agent
List all tenants, {page_size} per page.
Show every tenant where enabled is {enabled}, continuing from page token {page_token}.
POST /api/v0/tenants Create a tenant · Tenant service create tenant #
Ask an LLM
“How do I create a new tenant?”
“What do I need to provide to add a tenant?”
Tell an agent
Create a tenant named {name}.
Add a new tenant called {name}.
DELETE /api/v0/tenants/{tenant_id} Delete a tenant · Tenant service delete tenant #
Ask an LLM
“Can I permanently remove a tenant?”
“What is the way to delete a tenant I no longer use?”
Tell an agent destructive · confirm first
Delete tenant {tenant_id}.
Remove the tenant {tenant_id} permanently.
PATCH /api/v0/tenants/{tenant_id} Update a tenant · Tenant service update tenant #
Ask an LLM
“How do I rename or disable an existing tenant?”
“Can I update only certain tenant fields using an update mask?”
Tell an agent
Update tenant {tenant_id} with {tenant}.
Change only fields {update_mask} of tenant {tenant_id}.
POST /api/v0/tenants/{tenant_id}/invites Invite someone to a tenant · Tenant service invite member #
Ask an LLM
“How do I invite a colleague by email to join a tenant?”
“Can I choose the role a person gets when invited to a tenant?”
Tell an agent
Invite {email} to tenant {tenant_id}.
Send an invitation to {email} for tenant {tenant_id} with role {role}.
GET /api/v0/tenants/{tenant_id}/users List users in a tenant · Tenant service list tenant users #
Ask an LLM
“Who are the users in a given tenant?”
“Can I filter a tenant's users by role or email?”
Tell an agent
List the users in tenant {tenant_id}.
Show users of tenant {tenant_id} with role {role}, including their emails ({include_emails}).
POST /api/v0/tenants/{tenant_id}/users Add a user directly to a tenant · Tenant service provision user #
Ask an LLM
“Can I add a user to a tenant straight away without sending an invite?”
“How do I provision an account into a tenant with a specific role?”
Tell an agent
Provision {email} into tenant {tenant_id}.
Add user {email} to tenant {tenant_id} directly as {role}.
PATCH /api/v0/tenants/{tenant_id}/users/{user_id} Change a user's role in a tenant · Tenant service update tenant user #
Ask an LLM
“How do I promote or demote a user inside a tenant?”
“Can a tenant member's role be changed after they join?”
Tell an agent
Set the role of user {user_id} in tenant {tenant_id} to {role}.
Change {user_id}'s tenant role in {tenant_id}.
GET /api/v0/tenants/lookup Look up tenants by email or identity · Lookup tenants (internal) #
Ask an LLM
“Which tenants is a given email address associated with?”
“Can I find tenants for an identity ID using the internal lookup?”
Tell an agent
Look up the tenants for {email}.
Find tenants linked to identity {identity_id}.
GET /api/v0/users/{user_id}/tenants List a specific user's tenants · Tenant service list user tenants #
Ask an LLM
“Which tenants does a particular user belong to?”
“Can I see only the enabled tenants of another user?”
Tell an agent
List the tenants of user {user_id}.
Show the enabled ({enabled}) tenants for user {user_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://raw.githubusercontent.com/api-evangelist/canonical/refs/heads/main/openapi/canonical-tenantservice-api-openapi.yml

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-tenantservice-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

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-tenantservice-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 Tenant Service API
  version: '0.1'
tags:
- name: TenantService
paths:
  /api/v0/me/tenants:
    get:
      operationId: TenantService_ListMyTenants
      parameters:
      - in: query
        name: enabled
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantListMyTenantsResponse'
          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
      summary: Public Endpoints
      tags:
      - TenantService
  /api/v0/tenants:
    get:
      operationId: TenantService_ListTenants
      parameters:
      - in: query
        name: page_token
        schema:
          type: string
      - in: query
        name: page_size
        schema:
          format: int32
          type: integer
      - description: If set, only return tenants whose enabled status matches this value.
        in: query
        name: enabled
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantListTenantsResponse'
          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
      summary: Internal Admin Endpoints
      tags:
      - TenantService
    post:
      operationId: TenantService_CreateTenant
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tenantCreateTenantRequest'
        required: true
        x-originalParamName: body
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantCreateTenantResponse'
          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:
      - TenantService
      summary: Tenant service create tenant
      x-summary-source: derived
  /api/v0/tenants/{tenant_id}:
    delete:
      operationId: TenantService_DeleteTenant
      parameters:
      - in: path
        name: tenant_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantDeleteTenantResponse'
          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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Not found
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - TenantService
      summary: Tenant service delete tenant
      x-summary-source: derived
    patch:
      operationId: TenantService_UpdateTenant
      parameters:
      - in: path
        name: tenant_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantServiceUpdateTenantBody'
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantUpdateTenantResponse'
          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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Not found
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - TenantService
      summary: Tenant service update tenant
      x-summary-source: derived
  /api/v0/tenants/{tenant_id}/invites:
    post:
      operationId: TenantService_InviteMember
      parameters:
      - in: path
        name: tenant_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantServiceInviteMemberBody'
        required: true
        x-originalParamName: body
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantInviteMemberResponse'
          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:
      - TenantService
      summary: Tenant service invite member
      x-summary-source: derived
  /api/v0/tenants/{tenant_id}/users:
    get:
      operationId: TenantService_ListTenantUsers
      parameters:
      - in: path
        name: tenant_id
        required: true
        schema:
          type: string
      - in: query
        name: page_token
        schema:
          type: string
      - in: query
        name: page_size
        schema:
          format: int32
          type: integer
      - description: Exact match on membership role.
        in: query
        name: role
        schema:
          type: string
      - description: 'Exact match on user email. Resolved to identity_id in the service layer.

          Use identity_id instead when the caller already knows it, to skip the Kratos lookup.'
        in: query
        name: email
        schema:
          type: string
      - description: Exact match on Kratos identity ID. Takes precedence over email when both are set.
        in: query
        name: identity_id
        schema:
          type: string
      - description: 'When true, the response includes email addresses fetched from Kratos.

          When false (default), the email field is omitted and the Kratos call is skipped.'
        in: query
        name: include_emails
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantListTenantUsersResponse'
          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:
      - TenantService
      summary: Tenant service list tenant users
      x-summary-source: derived
    post:
      operationId: TenantService_ProvisionUser
      parameters:
      - in: path
        name: tenant_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantServiceProvisionUserBody'
        required: true
        x-originalParamName: body
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantProvisionUserResponse'
          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:
      - TenantService
      summary: Tenant service provision user
      x-summary-source: derived
  /api/v0/tenants/{tenant_id}/users/{user_id}:
    patch:
      operationId: TenantService_UpdateTenantUser
      parameters:
      - in: path
        name: tenant_id
        required: true
        schema:
          type: string
      - in: path
        name: user_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TenantServiceUpdateTenantUserBody'
        required: true
        x-originalParamName: body
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantUpdateTenantUserResponse'
          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
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Not found
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/typesErrorResponse'
          description: Internal server error
      tags:
      - TenantService
      summary: Tenant service update tenant user
      x-summary-source: derived
  /api/v0/tenants/lookup:
    get:
      description: Internal endpoint. Not intended for public API consumers.
      operationId: TenantService_LookupTenants
      parameters:
      - description: 'Exactly one of email or identity_id must be provided.

          When identity_id is set, the Kratos email-to-identity lookup is skipped.'
        in: query
        name: email
        schema:
          type: string
      - in: query
        name: identity_id
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantLookupTenantsResponse'
          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
      summary: Lookup tenants (internal)
      tags:
      - TenantService
      x-internal: true
  /api/v0/users/{user_id}/tenants:
    get:
      operationId: TenantService_ListUserTenants
      parameters:
      - in: path
        name: user_id
        required: true
        schema:
          type: string
      - description: If set, only return tenants whose enabled status matches this value.
        in: query
        name: enabled
        schema:
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tenantListUserTenantsResponse'
          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:
      - TenantService
      summary: Tenant service list user tenants
      x-summary-source: derived
components:
  schemas:
    tenantListTenantsResponse:
      properties:
        next_page_token:
          type: string
        tenants:
          items:
            $ref: '#/components/schemas/tenantTenant'
          type: array
      type: object
    tenantCreateTenantResponse:
      properties:
        tenant:
          $ref: '#/components/schemas/tenantTenant'
      type: object
    tenantCreateTenantRequest:
      properties:
        name:
          type: string
      type: object
    tenantUpdateTenantUserResponse:
      properties:
        user:
          $ref: '#/components/schemas/tenantTenantUser'
      type: object
    tenantListUserTenantsResponse:
      properties:
        tenants:
          items:
            $ref: '#/components/schemas/tenantTenant'
          type: array
      type: object
    tenantTenantUser:
      properties:
        email:
          type: string
        role:
          type: string
        user_id:
          type: string
      type: object
    tenantTenantInput:
      properties:
        enabled:
          type: boolean
        name:
          type: string
      type: object
    tenantDeleteTenantResponse:
      properties:
        message:
          type: string
        status:
          format: int32
          type: integer
      type: object
    TenantServiceUpdateTenantUserBody:
      properties:
        role:
          type: string
      type: object
    tenantProvisionUserResponse:
      properties:
        status:
          type: string
      type: object
    tenantListTenantUsersResponse:
      properties:
        next_page_token:
          type: string
        users:
          items:
            $ref: '#/components/schemas/tenantTenantUser'
          type: array
      type: object
    tenantLookupTenantsResponse:
      properties:
        tenants:
          items:
            $ref: '#/components/schemas/tenantTenant'
          type: array
      type: object
    tenantUpdateTenantResponse:
      properties:
        tenant:
          $ref: '#/components/schemas/tenantTenant'
      type: object
    tenantListMyTenantsResponse:
      properties:
        tenants:
          items:
            $ref: '#/components/schemas/tenantTenant'
          type: array
      type: object
    tenantInviteMemberResponse:
      properties:
        code:
          type: string
        link:
          type: string
        status:
          type: string
      type: object
    tenantTenant:
      properties:
        created_at:
          type: string
        enabled:
          type: boolean
        id:
          type: string
        name:
          type: string
      type: object
    TenantServiceProvisionUserBody:
      properties:
        email:
          type: string
        role:
          type: string
      type: object
    TenantServiceInviteMemberBody:
      properties:
        email:
          type: string
        role:
          type: string
      type: object
    typesErrorResponse:
      properties:
        message:
          type: string
        status:
          format: int32
          type: integer
      type: object
    TenantServiceUpdateTenantBody:
      properties:
        tenant:
          $ref: '#/components/schemas/tenantTenantInput'
        update_mask:
          type: string
      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