@workos/mcp-docs-server 0.1.0 → 0.2.0

package/.docs/organized/docs/reference/roles/index.mdx

@@ -1,268 +1,18 @@
 ---
-descriptions:
-  role:
-    self: 'The [Role](/reference/roles) object.'
-    object: Distinguishes the Role object.
-    id: Unique identifier of the Role.
-    name: A descriptive name for the Role. This field does not need to be unique.
-    slug: A unique key to reference the role.
-    description: A description for the Role.
-    permissions: A list of permission slugs assigned to the role.
-    type: 'The type of Role, either `EnvironmentRole` or `OrganizationRole`.'
-    created_at: The timestamp when the Role was last created.
-    updated_at: The timestamp when the Role was last updated.
-reference:
-  curl:
-    - url: /reference/roles
-      key: role
-      id: role
-      title: Role
-      properties:
-        - key: object
-          type: '"role"'
-          description: (role.object)
-        - key: id
-          type: string
-          description: (role.id)
-        - key: name
-          type: string
-          description: (role.name)
-        - key: slug
-          type: string
-          description: (role.slug)
-        - key: description
-          type: string | null
-          description: (role.description)
-        - key: type
-          type: '"EnvironmentRole" | "OrganizationRole"'
-          description: (role.type)
-        - key: created_at
-          type: string
-          description: (role.created_at)
-        - key: updated_at
-          type: string
-          description: (role.updated_at)
-  js:
-    - url: /reference/roles
-      key: Role
-      id: role
-      title: interface Role
-      properties:
-        - key: object
-          type: '"role"'
-          description: (role.object)
-        - key: id
-          type: string
-          description: (role.id)
-        - key: name
-          type: string
-          description: (role.name)
-        - key: slug
-          type: string
-          description: (role.slug)
-        - key: description
-          type: string | null
-          description: (role.description)
-        - key: permissions
-          type: 'string[]'
-          description: (role.permissions)
-        - key: type
-          type: '"EnvironmentRole" | "OrganizationRole"'
-          description: (role.type)
-        - key: createdAt
-          type: string
-          description: (role.created_at)
-        - key: updatedAt
-          type: string
-          description: (role.updated_at)
-  go:
-    - url: /reference/roles
-      key: Role
-      id: role
-      title: roles.Role
-      properties:
-        - key: ID
-          type: string
-          description: (role.id)
-        - key: Name
-          type: string
-          description: (role.name)
-        - key: Slug
-          type: string
-          description: (role.slug)
-        - key: Description
-          type: string
-          optional: true
-          description: (role.description)
-        - key: Type
-          type: RoleType
-          description: (role.type)
-        - key: CreatedAt
-          type: string
-          description: (role.created_at)
-        - key: UpdatedAt
-          type: string
-          description: (role.updated_at)
-  java:
-    - url: /reference/roles
-      key: Role
-      id: role
-      title: class Role
-      properties:
-        - key: obj
-          type: '"role"'
-          description: (role.object)
-        - key: id
-          type: String
-          description: (role.id)
-        - key: name
-          type: String
-          description: (role.name)
-        - key: slug
-          type: String
-          description: (role.slug)
-        - key: description
-          type: String
-          optional: true
-          description: (role.description)
-        - key: type
-          type: RoleType
-          description: (role.type)
-        - key: createdAt
-          type: String
-          description: (role.created_at)
-        - key: updatedAt
-          type: String
-          description: (role.updated_at)
-  python:
-    - url: /reference/roles
-      key: Role
-      id: role
-      title: Role
-      properties:
-        - key: object
-          type: '"role"'
-          description: (role.object)
-        - key: id
-          type: str
-          description: (role.id)
-        - key: name
-          type: str
-          description: (role.name)
-        - key: slug
-          type: str
-          description: (role.slug)
-        - key: description
-          type: str
-          optional: true
-          description: (role.description)
-        - key: type
-          type: '"EnvironmentRole" | "OrganizationRole"'
-          description: (role.type)
-        - key: created_at
-          type: str
-          description: (role.created_at)
-        - key: updated_at
-          type: str
-          description: (role.updated_at)
-  ruby:
-    - url: /reference/roles
-      key: Role
-      id: role
-      title: class Role
-      properties:
-        - key: object
-          type: '"role"'
-          description: (role.object)
-        - key: id
-          type: String
-          description: (role.id)
-        - key: name
-          type: String
-          description: (role.name)
-        - key: slug
-          type: String
-          description: (role.slug)
-        - key: description
-          type: String
-          optional: true
-          description: (role.description)
-        - key: type
-          type: '"EnvironmentRole" | "OrganizationRole"'
-          description: (role.type)
-        - key: created_at
-          type: String
-          description: (role.created_at)
-        - key: updated_at
-          type: String
-          description: (role.updated_at)
-  php:
-    - url: /reference/roles
-      id: role
-      key: Role
-      title: WorkOS\Resource\Role
-      properties:
-        - key: object
-          type: '"role"'
-          description: (role.object)
-        - key: id
-          type: string
-          description: (role.id)
-        - key: name
-          type: string
-          description: (role.name)
-        - key: slug
-          type: string
-          description: (role.slug)
-        - key: description
-          type: string
-          optional: true
-          description: (role.description)
-        - key: type
-          type: '"EnvironmentRole" | "OrganizationRole"'
-          description: (role.type)
-        - key: createdAt
-          type: string
-          description: (role.created_at)
-        - key: updatedAt
-          type: string
-          description: (role.updated_at)
-  dotnet:
-    - url: /reference/roles
-      key: Role
-      id: role
-      title: class Role
-      properties:
-        - key: Object
-          type: '"role"'
-          description: (role.object)
-        - key: Id
-          type: string
-          description: (role.id)
-        - key: Name
-          type: string
-          description: (role.name)
-        - key: Slug
-          type: string
-          description: (role.slug)
-        - key: Description
-          type: string
-          optional: true
-          description: (role.description)
-        - key: Type
-          type: RoleType
-          description: (role.type)
-        - key: CreatedAt
-          type: string
-          description: (organization.created_at)
-        - key: UpdatedAt
-          type: string
-          description: (organization.updated_at)
 originalPath: .tmp-workos-clone/packages/docs/content/reference/roles/index.mdx
 ---
-
 # Roles
 
-A role is an access control resource that can be assigned to [organization memberships](/reference/user-management/organization-membership), [directory users](/directory-sync/identity-provider-role-assignment), and [SSO profiles](/sso/identity-provider-role-assignment).
+The Authorization API provides endpoints for managing roles and permissions in your WorkOS environment. Use these endpoints to define access control structures that can be assigned to users, organization memberships, and more.
+
+## Environment Roles
+
+Environment roles are defined at the environment level and apply to all organizations. They provide a consistent set of roles that can be used throughout your application.
+
+## Organization Roles
+
+Organization roles are defined at the organization level and are specific to individual organizations. They allow organizations to create custom roles tailored to their needs.
+
+## Permissions
 
-<CodeBlock title="Example Role" file="role" referenceId="role" />
+Permissions are the individual access rights that are assigned to roles. They define what actions users with a given role can perform.

package/.docs/organized/docs/reference/roles/organization-role/add-permission.mdx

@@ -0,0 +1,75 @@
+---
+descriptions:
+  add_organization_role_permission:
+    slug: The slug of the permission to add to the role.
+reference:
+  curl:
+    - key: add_organization_role_permission
+      id: add_organization_role_permission
+      url: /reference/roles/organization-role/add-permission
+      title: '/authorization/organizations/:id/roles/:slug/permissions'
+      type: POST
+      parameters:
+        - key: slug
+          type: string
+          description: (add_organization_role_permission.slug)
+      returns:
+        - (organization_role)
+  js:
+    - key: addOrganizationRolePermission
+      id: add_organization_role_permission
+      url: /reference/roles/organization-role/add-permission
+      title: authorization.addOrganizationRolePermission()
+      parameters:
+        - key: organizationId
+          type: string
+          description: The ID of the organization.
+        - key: roleSlug
+          type: string
+          description: The slug of the role.
+        - key: options
+          type: object
+          unwrap: true
+          properties:
+            - key: permissionSlug
+              type: string
+              description: (add_organization_role_permission.slug)
+      returns:
+        - key: OrganizationRole
+          description: (organization_role.self)
+  python:
+    - key: add_organization_role_permission
+      id: add_organization_role_permission
+      url: /reference/roles/organization-role/add-permission
+      title: authorization.add_organization_role_permission()
+      parameters:
+        - key: organization_id
+          type: str
+          description: The ID of the organization.
+        - key: slug
+          type: str
+          description: The slug of the role.
+        - key: permission_slug
+          type: str
+          description: (add_organization_role_permission.slug)
+      returns:
+        - key: OrganizationRole
+          description: (organization_role.self)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/roles/organization-role/add-permission.mdx
+---
+
+## Add a permission to an organization role
+
+Add a single permission to an organization role. If the permission is already assigned to the role, this operation has no effect.
+
+<CodeBlock referenceId="add_organization_role_permission">
+  <CodeBlockTab
+    title="Request"
+    file="add-organization-role-permission-request"
+  />
+  <CodeBlockTab
+    title="Response"
+    file="add-organization-role-permission-response"
+  />
+</CodeBlock>

package/.docs/organized/docs/reference/roles/organization-role/create.mdx

@@ -0,0 +1,95 @@
+---
+descriptions:
+  create_organization_role:
+    slug: >-
+      A unique key to reference the role within the organization. Must begin
+      with `org-` and contain only lowercase letters, numbers, hyphens, and
+      underscores.
+    name: A descriptive name for the role.
+    description: An optional description for the role.
+reference:
+  curl:
+    - key: create_organization_role
+      id: create_organization_role
+      url: /reference/roles/organization-role/create
+      title: '/authorization/organizations/:id/roles'
+      type: POST
+      parameters:
+        - key: slug
+          type: string
+          description: (create_organization_role.slug)
+        - key: name
+          type: string
+          description: (create_organization_role.name)
+        - key: description
+          type: string
+          optional: true
+          description: (create_organization_role.description)
+      returns:
+        - (organization_role)
+  js:
+    - key: createOrganizationRole
+      id: create_organization_role
+      url: /reference/roles/organization-role/create
+      title: authorization.createOrganizationRole()
+      parameters:
+        - key: organizationId
+          type: string
+          description: The ID of the organization.
+        - key: options
+          type: object
+          unwrap: true
+          properties:
+            - key: slug
+              type: string
+              description: (create_organization_role.slug)
+            - key: name
+              type: string
+              description: (create_organization_role.name)
+            - key: description
+              type: string
+              optional: true
+              description: (create_organization_role.description)
+      returns:
+        - key: OrganizationRole
+          description: (organization_role.self)
+  python:
+    - key: create_organization_role
+      id: create_organization_role
+      url: /reference/roles/organization-role/create
+      title: authorization.create_organization_role()
+      parameters:
+        - key: organization_id
+          type: str
+          description: The ID of the organization.
+        - key: slug
+          type: str
+          description: (create_organization_role.slug)
+        - key: name
+          type: str
+          description: (create_organization_role.name)
+        - key: description
+          type: str
+          optional: true
+          description: (create_organization_role.description)
+      returns:
+        - key: OrganizationRole
+          description: (organization_role.self)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/roles/organization-role/create.mdx
+---
+
+## Create an organization role
+
+Create a new custom organization role. The role will be specific to the organization and can be assigned to organization memberships.
+
+The `slug` must be unique within the organization, begin with `org-`, and contain only lowercase letters, numbers, hyphens, and underscores.
+
+<Callout type="info">
+  New roles are placed at the bottom of the organization's priority order.
+</Callout>
+
+<CodeBlock referenceId="create_organization_role">
+  <CodeBlockTab title="Request" file="create-organization-role-request" />
+  <CodeBlockTab title="Response" file="create-organization-role-response" />
+</CodeBlock>

package/.docs/organized/docs/reference/roles/organization-role/delete.mdx

@@ -0,0 +1,47 @@
+---
+reference:
+  curl:
+    - key: delete_organization_role
+      id: delete_organization_role
+      url: /reference/roles/organization-role/delete
+      title: '/authorization/organizations/:id/roles/:slug'
+      type: DELETE
+  js:
+    - key: deleteOrganizationRole
+      id: delete_organization_role
+      url: /reference/roles/organization-role/delete
+      title: authorization.deleteOrganizationRole()
+      parameters:
+        - key: organizationId
+          type: string
+          description: The ID of the organization.
+        - key: slug
+          type: string
+          description: The slug of the role to delete.
+  python:
+    - key: delete_organization_role
+      id: delete_organization_role
+      url: /reference/roles/organization-role/delete
+      title: authorization.delete_organization_role()
+      parameters:
+        - key: organization_id
+          type: str
+          description: The ID of the organization.
+        - key: slug
+          type: str
+          description: The slug of the role to delete.
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/roles/organization-role/delete.mdx
+---
+
+## Delete an organization role
+
+Delete an existing custom organization role. The role must not have any active assignments or [IdP group role mappings](/rbac/idp-role-assignment).
+
+If the role has active assignments, you will receive a `409 Conflict` error with code `role_has_assignments`. If the role has group role mappings, you will receive a `409 Conflict` error with code `role_has_group_role_mappings`.
+
+<CodeBlock
+  title="Request"
+  file="delete-organization-role-request"
+  referenceId="delete_organization_role"
+/>

package/.docs/organized/docs/reference/roles/organization-role/get.mdx

@@ -0,0 +1,55 @@
+---
+descriptions:
+  get_organization_role:
+    slug: The unique slug of the role to retrieve.
+reference:
+  curl:
+    - key: get_organization_role
+      id: get_organization_role
+      url: /reference/roles/organization-role/get
+      title: '/authorization/organizations/:id/roles/:slug'
+      type: GET
+      returns:
+        - (organization_role)
+  js:
+    - key: getOrganizationRole
+      id: get_organization_role
+      url: /reference/roles/organization-role/get
+      title: authorization.getOrganizationRole()
+      parameters:
+        - key: organizationId
+          type: string
+          description: The ID of the organization.
+        - key: slug
+          type: string
+          description: (get_organization_role.slug)
+      returns:
+        - key: OrganizationRole
+          description: (organization_role.self)
+  python:
+    - key: get_organization_role
+      id: get_organization_role
+      url: /reference/roles/organization-role/get
+      title: authorization.get_organization_role()
+      parameters:
+        - key: organization_id
+          type: str
+          description: The ID of the organization.
+        - key: slug
+          type: str
+          description: (get_organization_role.slug)
+      returns:
+        - key: OrganizationRole
+          description: (organization_role.self)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/roles/organization-role/get.mdx
+---
+
+## Get an organization role
+
+Retrieve a role that applies to an organization by its slug. This can return either an environment role or an organization-specific role.
+
+<CodeBlock referenceId="get_organization_role">
+  <CodeBlockTab title="Request" file="get-organization-role-request" />
+  <CodeBlockTab title="Response" file="get-organization-role-response" />
+</CodeBlock>

package/.docs/organized/docs/reference/roles/organization-role/index.mdx

@@ -0,0 +1,148 @@
+---
+descriptions:
+  organization_role:
+    self: 'The [Organization Role](/reference/roles/organization-role) object.'
+    object: Distinguishes the Role object.
+    id: Unique identifier of the Role.
+    name: A descriptive name for the Role. This field does not need to be unique.
+    slug: >-
+      A unique key to reference the role within the organization. Must be
+      lowercase and contain only letters, numbers, hyphens, and underscores.
+    description: A description for the Role.
+    permissions: A list of permission slugs assigned to the role.
+    type: >-
+      The type of Role. For organization roles, this is always
+      `OrganizationRole`.
+    resource_type_slug: The slug of the resource type the role is scoped to.
+    created_at: The timestamp when the Role was created.
+    updated_at: The timestamp when the Role was last updated.
+reference:
+  curl:
+    - url: /reference/roles/organization-role
+      key: organization_role
+      id: organization_role
+      title: Organization Role
+      properties:
+        - key: object
+          type: '"role"'
+          description: (organization_role.object)
+        - key: id
+          type: string
+          description: (organization_role.id)
+        - key: name
+          type: string
+          description: (organization_role.name)
+        - key: slug
+          type: string
+          description: (organization_role.slug)
+        - key: description
+          type: string | null
+          description: (organization_role.description)
+        - key: permissions
+          type: 'string[]'
+          description: (organization_role.permissions)
+        - key: type
+          type: '"OrganizationRole"'
+          description: (organization_role.type)
+        - key: resource_type_slug
+          type: string
+          description: (organization_role.resource_type_slug)
+        - key: created_at
+          type: string
+          description: (organization_role.created_at)
+        - key: updated_at
+          type: string
+          description: (organization_role.updated_at)
+  js:
+    - url: /reference/roles/organization-role
+      key: OrganizationRole
+      id: organization_role
+      title: OrganizationRole
+      properties:
+        - key: object
+          type: '"role"'
+          description: (organization_role.object)
+        - key: id
+          type: string
+          description: (organization_role.id)
+        - key: name
+          type: string
+          description: (organization_role.name)
+        - key: slug
+          type: string
+          description: (organization_role.slug)
+        - key: description
+          type: string | null
+          description: (organization_role.description)
+        - key: permissions
+          type: 'string[]'
+          description: (organization_role.permissions)
+        - key: type
+          type: '"OrganizationRole"'
+          description: (organization_role.type)
+        - key: resourceTypeSlug
+          type: string
+          description: (organization_role.resource_type_slug)
+        - key: createdAt
+          type: string
+          description: (organization_role.created_at)
+        - key: updatedAt
+          type: string
+          description: (organization_role.updated_at)
+  python:
+    - url: /reference/roles/organization-role
+      key: OrganizationRole
+      id: organization_role
+      title: OrganizationRole
+      properties:
+        - key: object
+          type: str
+          description: (organization_role.object)
+        - key: id
+          type: str
+          description: (organization_role.id)
+        - key: name
+          type: str
+          description: (organization_role.name)
+        - key: slug
+          type: str
+          description: (organization_role.slug)
+        - key: description
+          type: str | None
+          description: (organization_role.description)
+        - key: permissions
+          type: 'list[str]'
+          description: (organization_role.permissions)
+        - key: type
+          type: str
+          description: (organization_role.type)
+        - key: resource_type_slug
+          type: str
+          description: (organization_role.resource_type_slug)
+        - key: created_at
+          type: str
+          description: (organization_role.created_at)
+        - key: updated_at
+          type: str
+          description: (organization_role.updated_at)
+originalPath: >-
+  .tmp-workos-clone/packages/docs/content/reference/roles/organization-role/index.mdx
+---
+
+# Organization Role
+
+An organization role is an access control resource defined at the organization level. Organization roles allow individual organizations to create custom roles tailored to their specific needs, in addition to the environment roles that apply across all organizations.
+
+Like environment roles, organization roles can be assigned to [organization memberships](/reference/authkit/organization-membership), [directory users](/directory-sync/identity-provider-role-assignment), and [SSO profiles](/sso/identity-provider-role-assignment). Each organization role has a unique slug identifier within the organization and can have permissions assigned to it.
+
+<Callout type="info">
+  When listing roles for an organization, both environment roles and
+  organization roles are returned in priority order. Environment roles are
+  included because they apply to all organizations in your environment.
+</Callout>
+
+<CodeBlock
+  title="Organization Role"
+  file="organization-role"
+  referenceId="organization_role"
+/>