Kinde Organizations API

openapi: 3.0.0
info:
  version: '1'
  title: Kinde Account API Keys Organizations API
  description: '

    Provides endpoints to operate on an authenticated user.


    ## Intro


    ## How to use


    1. Get a user access token - this can be obtained when a user signs in via the methods you''ve setup in Kinde (e.g. Google, passwordless, etc).


    2. Call one of the endpoints below using the user access token in the Authorization header as a Bearer token. Typically, you can use the `getToken` command in the relevant SDK.

    '
  termsOfService: https://docs.kinde.com/trust-center/agreements/terms-of-service/
  contact:
    name: Kinde Support Team
    email: support@kinde.com
    url: https://docs.kinde.com
tags:
- name: Organizations
  x-displayName: Organizations
paths:
  /api/v1/organization/{org_code}/invites:
    servers: []
    get:
      tags:
      - Organizations
      operationId: getOrganizationInvites
      x-scope: read:organization_invites
      summary: Get organization invites
      description: "Get a list of invitations for an organization. By default, only pending (non-revoked, non-accepted) invitations are returned.\n\n<div>\n  <code>read:organization_invites</code>\n</div>\n"
      parameters:
      - name: org_code
        in: path
        description: The organization's code.
        required: true
        schema:
          type: string
          example: org_1ccfb819462
      - name: sort
        in: query
        description: Field and order to sort the result by.
        schema:
          type: string
          nullable: true
          enum:
          - created_on_asc
          - created_on_desc
          - email_asc
          - email_desc
          - name_asc
          - name_desc
          example: created_on_desc
      - name: page_size
        in: query
        description: Number of results per page. Defaults to 10 if parameter not sent.
        schema:
          type: integer
          nullable: true
          example: 10
      - name: next_token
        in: query
        description: A string to get the next page of results if there are more results.
        schema:
          type: string
          nullable: true
      - name: include_revoked
        in: query
        description: Include revoked invitations in the results.
        schema:
          type: boolean
          nullable: true
          default: false
      - name: include_accepted
        in: query
        description: Include accepted invitations in the results.
        schema:
          type: boolean
          nullable: true
          default: false
      responses:
        '200':
          description: Invitations successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_organization_invites_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    post:
      tags:
      - Organizations
      operationId: createOrganizationInvite
      x-scope: create:organization_invites
      summary: Create organization invite
      description: "Create a new invitation for an organization. An invitation email will be sent to the provided email address if `send_email` is set to `true`.\n\nInvitations cannot be created for organizations that are managed by directory sync; user and role changes for those organizations must be made in the upstream identity provider.\n\nRoles that require an explicit assignment permission cannot be granted to an invitee unless the caller (or the user the token represents) holds that permission. On Kinde-hosted plans, roles outside `owner`/`admin` additionally require the `extended_roles` entitlement.\n\nPer-organization rate limits apply: a maximum number of invitations may be created per rolling 24 hour window, and a maximum number of active (non-accepted, non-revoked) invitations may exist at any time. Requests that exceed either limit are rejected.\n\n<div>\n  <code>create:organization_invites</code>\n</div>\n"
      parameters:
      - name: org_code
        in: path
        description: The organization's code.
        required: true
        schema:
          type: string
          example: org_1ccfb819462
      requestBody:
        description: Invitation details. `email` is capped at 254 characters (RFC 5321). `first_name` and `last_name` are capped at 64 characters each. Inputs over these limits are rejected with `EMAIL_TOO_LONG`, `FIRST_NAME_TOO_LONG`, or `LAST_NAME_TOO_LONG`.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              - roles
              properties:
                email:
                  description: The email address of the user to invite. Maximum 254 characters.
                  type: string
                  maxLength: 254
                  example: user@example.com
                first_name:
                  description: The first name of the user to invite. Maximum 64 characters.
                  type: string
                  maxLength: 64
                  nullable: true
                  example: John
                last_name:
                  description: The last name of the user to invite. Maximum 64 characters.
                  type: string
                  maxLength: 64
                  nullable: true
                  example: Doe
                roles:
                  description: Array of role keys to assign to the user.
                  type: array
                  items:
                    type: string
                  example:
                  - admin
                  - manager
                send_email:
                  description: Whether to send an invitation email to the user. Defaults to false.
                  type: boolean
                  default: false
      responses:
        '201':
          description: Invitation successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_organization_invite_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/organization/{org_code}/invites/{invite_code}:
    servers: []
    get:
      tags:
      - Organizations
      operationId: getOrganizationInvite
      x-scope: read:organization_invites
      summary: Get organization invite
      description: "Get details of a specific invitation by its code.\n\n<div>\n  <code>read:organization_invites</code>\n</div>\n"
      parameters:
      - name: org_code
        in: path
        description: The organization's code.
        required: true
        schema:
          type: string
          example: org_1ccfb819462
      - name: invite_code
        in: path
        description: The invitation's code.
        required: true
        schema:
          type: string
          example: inv_abc123def456
      responses:
        '200':
          description: Invitation successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_organization_invite_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    delete:
      tags:
      - Organizations
      operationId: deleteOrganizationInvite
      x-scope: delete:organization_invites
      summary: Delete organization invite
      description: "Revoke (delete) an invitation. This will mark the invitation as revoked and prevent it from being accepted.\n\n<div>\n  <code>delete:organization_invites</code>\n</div>\n"
      parameters:
      - name: org_code
        in: path
        description: The organization's code.
        required: true
        schema:
          type: string
          example: org_1ccfb819462
      - name: invite_code
        in: path
        description: The invitation's code.
        required: true
        schema:
          type: string
          example: inv_abc123def456
      responses:
        '200':
          description: Invitation successfully revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/organization:
    servers: []
    get:
      tags:
      - Organizations
      operationId: getOrganization
      x-scope: read:organizations
      summary: Get organization
      description: "Retrieve organization details by code.\n\n<div>\n  <code>read:organizations</code>\n</div>\n"
      parameters:
      - in: query
        name: code
        description: The organization's code.
        schema:
          type: string
          example: org_1ccfb819462
      - in: query
        name: expand
        description: 'Additional data to include in the response. Allowed value: "billing".'
        schema:
          type: string
          example: billing
      responses:
        '200':
          description: Organization successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_organization_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    post:
      tags:
      - Organizations
      operationId: createOrganization
      x-scope: create:organizations
      summary: Create organization
      description: "Create a new organization. To learn more read about [multi tenancy using organizations](https://docs.kinde.com/build/organizations/multi-tenancy-using-organizations/)\n\n<div>\n  <code>create:organizations</code>\n</div>\n"
      requestBody:
        description: Organization details.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  description: The organization's name.
                  type: string
                  example: Acme Corp
                feature_flags:
                  type: object
                  description: The organization's feature flag settings.
                  additionalProperties:
                    type: string
                    enum:
                    - str
                    - int
                    - bool
                    description: Value of the feature flag.
                external_id:
                  description: The organization's external identifier - commonly used when migrating from or mapping to other systems.
                  type: string
                  example: some1234
                background_color:
                  description: The organization's brand settings - background color.
                  type: string
                button_color:
                  description: The organization's brand settings - button color.
                  type: string
                button_text_color:
                  description: The organization's brand settings - button text color.
                  type: string
                link_color:
                  description: The organization's brand settings - link color.
                  type: string
                background_color_dark:
                  description: The organization's brand settings - dark mode background color.
                  type: string
                button_color_dark:
                  description: The organization's brand settings - dark mode button color.
                  type: string
                button_text_color_dark:
                  description: The organization's brand settings - dark mode button text color.
                  type: string
                link_color_dark:
                  description: The organization's brand settings - dark mode link color.
                  type: string
                theme_code:
                  description: The organization's brand settings - theme/mode 'light' | 'dark' | 'user_preference'.
                  type: string
                handle:
                  description: A unique handle for the organization - can be used for dynamic callback urls.
                  type: string
                  example: acme_corp
                is_allow_registrations:
                  deprecated: true
                  description: Deprecated - Use 'is_auto_membership_enabled' instead.
                  type: boolean
                  example: true
                is_auto_membership_enabled:
                  description: If users become members of this organization when the org code is supplied during authentication.
                  type: boolean
                  example: true
                sender_name:
                  nullable: true
                  type: string
                  example: Acme Corp
                  description: The name of the organization that will be used in emails
                sender_email:
                  nullable: true
                  type: string
                  example: hello@acmecorp.com
                  description: The email address that will be used in emails. Requires custom SMTP to be set up.
                is_create_billing_customer:
                  type: boolean
                  example: false
                  description: If a billing customer is also created for this organization
                billing_email:
                  type: string
                  example: billing@acmecorp.com
                  description: The email address used for billing purposes for the organization
                billing_plan_code:
                  type: string
                  example: pro
                  description: The billing plan to put the customer on. If not specified, the default plan is used
      responses:
        '200':
          description: Organization successfully created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/create_organization_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/organizations:
    servers: []
    get:
      tags:
      - Organizations
      operationId: getOrganizations
      x-scope: read:organizations
      summary: Get organizations
      description: "Get a list of organizations.\n\n<div>\n  <code>read:organizations</code>\n</div>\n"
      parameters:
      - name: sort
        in: query
        description: Field and order to sort the result by.
        schema:
          type: string
          nullable: true
          enum:
          - name_asc
          - name_desc
          - email_asc
          - email_desc
      - name: page_size
        in: query
        description: Number of results per page. Defaults to 10 if parameter not sent.
        schema:
          type: integer
          nullable: true
      - name: next_token
        in: query
        description: A string to get the next page of results if there are more results.
        schema:
          type: string
          nullable: true
      responses:
        '200':
          description: Organizations successfully retreived.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_organizations_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/organization/{org_code}:
    servers: []
    patch:
      tags:
      - Organizations
      operationId: updateOrganization
      description: "Update an organization.\n\n<div>\n  <code>update:organizations</code>\n</div>\n"
      summary: Update Organization
      parameters:
      - name: org_code
        in: path
        description: The identifier for the organization.
        required: true
        schema:
          type: string
          example: org_1ccfb819462
      - name: expand
        in: query
        description: 'Additional data to include in the response. Allowed value: "billing".'
        required: false
        schema:
          type: string
          nullable: true
          enum:
          - billing
      requestBody:
        description: Organization details.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: The organization's name.
                  type: string
                  example: Acme Corp
                external_id:
                  description: The organization's ID.
                  type: string
                  example: some1234
                background_color:
                  description: The organization's brand settings - background color.
                  type: string
                  example: '#fff'
                button_color:
                  description: The organization's brand settings - button color.
                  type: string
                  example: '#fff'
                button_text_color:
                  description: The organization's brand settings - button text color.
                  type: string
                  example: '#fff'
                link_color:
                  description: The organization's brand settings - link color.
                  type: string
                  example: '#fff'
                background_color_dark:
                  description: The organization's brand settings - dark mode background color.
                  type: string
                  example: '#000'
                button_color_dark:
                  description: The organization's brand settings - dark mode button color.
                  type: string
                  example: '#000'
                button_text_color_dark:
                  description: The organization's brand settings - dark mode button text color.
                  type: string
                  example: '#000'
                link_color_dark:
                  description: The organization's brand settings - dark mode link color.
                  type: string
                  example: '#000'
                theme_code:
                  description: The organization's brand settings - theme/mode.
                  type: string
                  enum:
                  - light
                  - dark
                  - user_preference
                  example: light
                handle:
                  description: The organization's handle.
                  type: string
                  example: acme_corp
                is_allow_registrations:
                  deprecated: true
                  description: Deprecated - Use 'is_auto_membership_enabled' instead.
                  type: boolean
                is_auto_membership_enabled:
                  description: If users become members of this organization when the org code is supplied during authentication.
                  type: boolean
                  example: true
                is_auto_join_domain_list:
                  description: Users can sign up to this organization.
                  type: boolean
                  example: true
                allowed_domains:
                  description: Domains allowed for self-sign up to this environment.
                  type: array
                  example:
                  - https://acme.kinde.com
                  - https://acme.com
                  items:
                    type: string
                is_enable_advanced_orgs:
                  description: Activate advanced organization features.
                  type: boolean
                  example: true
                is_enforce_mfa:
                  description: Enforce MFA for all users in this organization.
                  type: boolean
                  example: true
                sender_name:
                  nullable: true
                  type: string
                  example: Acme Corp
                  description: The name of the organization that will be used in emails
                sender_email:
                  nullable: true
                  type: string
                  example: hello@acmecorp.com
                  description: The email address that will be used in emails. Requires custom SMTP to be set up.
                is_suspended:
                  type: boolean
                  description: Whether to suspend or unsuspend the organization. Setting to true suspends the organization; setting to false unsuspends it. The default organization cannot be suspended.
                  example: false
      responses:
        '200':
          description: Organization successfully updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    delete:
      tags:
      - Organizations
      operationId: deleteOrganization
      description: "Delete an organization.\n\n<div>\n  <code>delete:organizations</code>\n</div>\n"
      summary: Delete Organization
      parameters:
      - name: org_code
        in: path
        description: The identifier for the organization.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Organization successfully deleted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/organizations/{org_code}/users:
    servers: []
    get:
      tags:
      - Organizations
      operationId: GetOrganizationUsers
      x-scope: read:organization_users
      summary: Get organization users
      description: "Get user details for all members of an organization.\n\n<div>\n  <code>read:organization_users</code>\n</div>\n"
      parameters:
      - name: sort
        in: query
        description: Field and order to sort the result by.
        schema:
          example: email_asc
          type: string
          nullable: true
          enum:
          - name_asc
          - name_desc
          - email_asc
          - email_desc
          - id_asc
          - id_desc
      - name: page_size
        in: query
        description: Number of results per page. Defaults to 10 if parameter not sent.
        schema:
          example: 10
          type: integer
          nullable: true
      - name: next_token
        in: query
        description: A string to get the next page of results if there are more results.
        schema:
          example: MTo6OmlkX2FzYw==
          type: string
          nullable: true
      - name: org_code
        in: path
        description: The organization's code.
        required: true
        schema:
          example: org_1ccfb819462
          type: string
          nullable: false
      - name: permissions
        in: query
        description: Filter by user permissions comma separated (where all match)
        schema:
          example: admin
          type: string
      - name: roles
        in: query
        description: Filter by user roles comma separated (where all match)
        schema:
          example: manager
          type: string
      responses:
        '200':
          description: A successful response with a list of organization users or an empty list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_organization_users_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    post:
      tags:
      - Organizations
      operationId: AddOrganizationUsers
      description: "Add existing users to an organization.\n\n<div>\n  <code>create:organization_users</code>\n</div>\n"
      summary: Add Organization Users
      parameters:
      - name: org_code
        in: path
        description: The organization's code.
        required: true
        schema:
          type: string
          nullable: false
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                users:
                  description: Users to be added to the organization.
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        description: The users id.
                        type: string
                        example: kp_057ee6debc624c70947b6ba512908c35
                      roles:
                        description: Role keys to assign to the user.
                        type: array
                        items:
                          type: string
                          example: manager
                      permissions:
                        description: Permission keys to assign to the user.
                        type: array
                        items:
                          type: string
                          example: admin
      responses:
        '200':
          description: Add organization users request successfully processed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/add_organization_users_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
    patch:
      tags:
      - Organizations
      operationId: UpdateOrganizationUsers
      description: "Update users that belong to an organization.\n\n<div>\n  <code>update:organization_users</code>\n</div>\n"
      summary: Update Organization Users
      parameters:
      - name: org_code
        in: path
        description: The organization's code.
        required: true
        schema:
          type: string
          nullable: false
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                users:
                  description: Users to add, update or remove from the organization.
                  type: array
                  items:
                    type: object
                    properties:
                      id:
                        description: The users id.
                        type: string
                        example: kp_057ee6debc624c70947b6ba512908c35
                      operation:
                        description: Optional operation, set to 'delete' to remove the user from the organization.
                        type: string
                        example: delete
                      roles:
                        description: Role keys to assign to the user.
                        type: array
                        items:
                          type: string
                          example: manager
                      permissions:
                        description: Permission keys to assign to the user.
                        type: array
                        items:
                          type: string
                          example: admin
      responses:
        '200':
          description: Users successfully removed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/update_organization_users_response'
        '400':
          $ref: '#/components/responses/bad_request'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/too_many_requests'
      security:
      - kindeBearerAuth: []
  /api/v1/organizations/{org_code}/users/{user_id}/roles:
    servers: []
    get:
      tags:
      - Organizations
      operationId: GetOrganizationUserRoles
      x-scope: read:organization_user_roles
      description: "Get roles for an organization user.\n\n<div>\n  <code>read:organization_user_roles</code>\n</div>\n"
      summary: List Organization User Roles
      parameters:
      - name: org_code
        in: path
        description: The organization's code.
        required: true
        schema:
          type: string
          nullable: false
      - name: user_id
        in: path
        description: The user's id.
        required: true
        schema:
          type: string
          nullable: false
      responses:
        '200':
          description: A successful response with a list of user roles.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_organizations_user_roles_response'
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/get_organizations_user_roles_response'
        '403':
          description: Invalid credentials.
        '429':
          description: Request was throttled.
      security:
      - kindeBearerAuth: []
    post:
      tags:
      - Organizations
      operationId: CreateOrganizationUserRole
      description: "Add role to an organization user.\n\n<div>\n  <code>create:organization_user_roles</code>\n</div>\n"
      summary: Add Organization User Role
      parameters:
      - name: org_code
        in: path
        description: The organization's code.
        required: true
        schema:
          type: string
          nullable: false
      - name: user_id
        in: path
        description: The user's id.
        required: true
        schema:
          type: string
          nullable: false
      requestBody:
        description: Role details.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role_id:
                  description: The role id.
                  type: string
      responses:
        '200':
          description: Role successfully added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success_response'
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/success_response'
        '403':
          description: Invalid credentials.
        '429':
          description: Request was throttled.
      security:
      - kindeBearerAuth: []
  /api/v1/organizations/{org_code}/users/{user_id}/roles/{role_id}:
    servers: []
    delete:
      tags:
      - Organizations
    

# --- truncated at 32 KB (98 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kinde/refs/heads/main/openapi/kinde-organizations-api-openapi.yml