Hoshin Kanri Identity API

openapi: 3.2.0
info:
  title: Hoshin Kanri Identity API
  version: 0.9.0
  description: 'Beta: operations and fields may still change. Covers the operations the Hoshin MCP server uses. For an AI agent, prefer MCP at https://hoshin.app/mcp. An admin creates a token from the API tokens link in the app header. Error messages are in English; rely on the `error` code.'
servers:
- url: https://hoshin.app
tags:
- name: Identity
paths:
  /api/whoami:
    get:
      operationId: whoami
      tags:
      - Identity
      summary: Who is calling, with what rights, under which plan
      description: The organization, the member behind this connection, the role this connection actually has (member role capped by the token permissions or OAuth scopes, and by the plan), the plan with its limits and usage, and which active matrices this connection may edit. Read it before a write.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Whoami'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/members:
    get:
      operationId: listMembers
      tags:
      - Identity
      summary: 'The directory of the organization: who can own an element'
      description: Active members, name and id only. Pass the id as ownerId.
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  members:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        displayName:
                          type: string
                        isActive:
                          type: boolean
                      required:
                      - id
                      - displayName
                      - isActive
                    description: 'Active members: who can own an element (owner_id).'
                required:
                - members
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/capability-requests:
    post:
      operationId: reportMissingCapability
      tags:
      - Identity
      summary: Tell us what you needed and did not find
      description: Describe the capability, not your strategy. A viewer may ask. Counted per organization; when `feature` names a capability we list as not built, it counts toward building it. Our own organizations are heard but never counted; the public demo and test organizations are refused with INTERNAL_ORG.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                capability:
                  type: string
                  minLength: 3
                  maxLength: 300
                  description: What is missing, in one sentence.
                useCase:
                  type: string
                  maxLength: 1000
                  description: What you were trying to do when you needed it.
                feature:
                  type: string
                  enum:
                  - agent-inbox-token
                  - saml
                  - claude-ema
                  - client-encryption
                  - kpi-alerts
                  - on-prem
                  - matrix-orientation
                  - a3-initiative
                  description: When it is one of the capabilities we already list as not built.
              required:
              - capability
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                    enum:
                    - true
                  countedAs:
                    type:
                    - string
                    - 'null'
                    enum:
                    - agent-inbox-token
                    - saml
                    - claude-ema
                    - client-encryption
                    - kpi-alerts
                    - on-prem
                    - matrix-orientation
                    - a3-initiative
                    - null
                    description: The listed capability this request was counted for, if any.
                required:
                - ok
                - countedAs
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Stable machine-readable code, among them UNAUTHORIZED, FORBIDDEN, MATRIX_EDIT_RESTRICTED, DEFAULT_MATRIX_ADMIN_ONLY, NOT_FOUND, INVALID_ID, VALIDATION_ERROR, EMPTY_UPDATE, NOT_ADJACENT, TOO_MANY_SHARES.
        message:
          type: string
        issues:
          type: array
          items:
            type: object
            additionalProperties: {}
          description: Invalid fields, on VALIDATION_ERROR.
      required:
      - error
    Whoami:
      type: object
      properties:
        organization:
          type: object
          properties:
            name:
              type: string
            slug:
              type: string
          required:
          - name
          - slug
        you:
          type: object
          properties:
            displayName:
              type:
              - string
              - 'null'
            memberRole:
              type: string
              enum:
              - super_admin
              - owner
              - admin
              - editor
              - viewer
              description: Your role as a member of the organization.
          required:
          - displayName
          - memberRole
        connection:
          type: object
          properties:
            kind:
              type: string
              enum:
              - session
              - api_token
              - oauth
            effectiveRole:
              type: string
              enum:
              - super_admin
              - owner
              - admin
              - editor
              - viewer
              description: 'What this connection may do: the member role, capped by the token, its scopes and the plan.'
            canWrite:
              type: boolean
            tokenName:
              type: string
            permissions:
              type: array
              items:
                type: string
            clientId:
              type: string
            scopes:
              type: array
              items:
                type: string
            planCapped:
              type: boolean
              description: True when the plan alone holds this connection at read-only.
          required:
          - kind
          - effectiveRole
          - canWrite
          - planCapped
        plan:
          type: object
          properties:
            plan:
              type: string
              enum:
              - free
              - pro
              - enterprise
            label:
              type: string
            enforced:
              type: boolean
              description: 'False while the beta keeps everything unlocked: the limits are shown, not applied.'
            limits:
              type: object
              properties:
                matrices:
                  type:
                  - integer
                  - 'null'
                users:
                  type:
                  - integer
                  - 'null'
                agentWrite:
                  type: boolean
              required:
              - matrices
              - users
              - agentWrite
            usage:
              type: object
              properties:
                matrices:
                  type: integer
                  description: 'Archived ones included: they count toward the limit.'
                users:
                  type: integer
                  description: Active members, pending invitations included.
              required:
              - matrices
              - users
          required:
          - plan
          - label
          - enforced
          - limits
          - usage
        matrices:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                format: uuid
              name:
                type: string
              isDefault:
                type: boolean
              canEdit:
                type: boolean
            required:
            - id
            - name
            - isDefault
            - canEdit
        otherOrganizations:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              slug:
                type: string
            required:
            - name
            - slug
          description: 'The other organizations of the same person, to the browser session only (empty through an API token or OAuth: a client authorized for one organization does not learn the others). A connection acts in one organization: to act in another, the person connects the client again and chooses it on the consent screen.'
        notes:
          type: array
          items:
            type: string
      required:
      - organization
      - you
      - connection
      - plan
      - matrices
      - otherOrganizations
      - notes
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An API token, hk_..., or an OAuth 2.1 access token. OAuth needs PKCE S256 and a registered client: https://hoshin.app/.well-known/oauth-authorization-server'