> ## Documentation Index
> Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Apply a workspace member lifecycle action

> Runs a lifecycle action. Effects are limited to this workspace. At most 10 actions per member per hour.

| action | Allowed from | Result |
| --- | --- | --- |
| `deactivate` | active, suspended, locked | `deactivated`; workspace sessions end |
| `suspend` | active | `suspended`; workspace sessions end |
| `reactivate` | suspended, deactivated, locked | `active`; a sign-in lockout returns `409 LOCKED_BY_LOGIN_LOCKOUT` |
| `reset_mfa` | active, locked | MFA enrolment cleared |
| `revoke_sessions` | active, suspended, locked | workspace sessions end; status unchanged |
| `resend_invite` | pending, expired | new invitation, expiry restarted |

Any other combination returns `409 INVALID_STATE_TRANSITION`.

**Required scope:** `workspace.members.write`

Using this API, you can apply a lifecycle action on a member. The actions to manage workspace members are `deactivate`, `suspend`, `reactivate`, `reset_mfa`, `revoke_sessions`, and `resend_invite`. This API request updates only a single workspace. The request needs the `workspace.members.write` scope. A successful response returns the updated member and the previous status.

> [!NOTE]
>
> The platform allows a maximum of 10 actions per hour per member.

The applicable actions work only on specific existing statuses.

* `suspend` works only on an `active` member.
* `resend_invite` works only on a `pending` or `expired` member.

An inapplicable status combination returns the error `409 INVALID_STATE_TRANSITION`.


## OpenAPI

````yaml agent-platform/api-specs/user-management.yaml post /api/public/v1/workspaces/{workspaceId}/members/{memberId}/actions
openapi: 3.0.3
info:
  title: Artemis User and Role Management API
  version: 1.9.1
  description: >-
    Provision, update and remove workspace and project members from an identity
    provider, HR system or script.


    **Authentication.** Send a platform key in `X-API-Key` or as `Authorization:
    Bearer <key>`. Workspace endpoints need a workspace platform key
    (`abl_ws_…`), created by a workspace Owner or Admin under **Settings >
    Secrets > Platform Keys**. Project endpoints also accept a project platform
    key bound to that project. User session and SDK tokens are rejected with
    `401`.


    **Scopes.** `workspace.members.read`, `workspace.members.write`,
    `workspace.roles.read`, `project.members.read`, `project.members.write`. A
    missing scope returns `403 INSUFFICIENT_SCOPE`.


    **Roles a key can assign.** Workspace:
    `builtin.workspace.restricted_member`,
    `builtin.workspace.workbench_manager`. Project: `builtin.project.developer`,
    `builtin.project.tester`, `builtin.project.viewer`,
    `builtin.project.workbench_manager`. Owner, Admin, Auditor, project Admin,
    the built-in Operator/Member/Viewer workspace roles and custom roles are
    never assignable by a key. The roles endpoints return `assignableByCaller`
    per role.


    **Envelope.** Success: `{ "success": true, "data": … }`. Error: `{
    "success": false, "error": { "code", "message", "details" } }`. Every
    response carries `X-Request-Id`.


    **Limits.** Per key: 300 reads/min, 60 writes/min (1,000 items), 300
    removals/min, 5 requests in flight. Per workspace: 1,000 reads/min, 200
    writes/min (3,000 items), 600 removals/min. Batches: 100 items, 1 MiB.
    Invitation email: 500/hour per workspace, 3 per address per 24 hours.
    Exceeding a limit returns `429` with `Retry-After`.
servers:
  - url: https://{platformHost}
    description: Your regional Artemis platform host
    variables:
      platformHost:
        default: platform.example.com
        description: Region-specific platform host.
security:
  - platformApiKey: []
  - bearerPlatformKey: []
tags:
  - name: Workspace members
    description: >-
      Invite, list, update, remove and run lifecycle actions on workspace
      members.
  - name: Roles
    description: Read built-in workspace and project roles.
  - name: Projects
    description: Discover the workspace’s projects.
  - name: Project members
    description: Add, list, update and remove project members.
paths:
  /api/public/v1/workspaces/{workspaceId}/members/{memberId}/actions:
    post:
      tags:
        - Workspace members
      summary: Apply a workspace member lifecycle action
      description: >-
        Runs a lifecycle action. Effects are limited to this workspace. At most
        10 actions per member per hour.


        | action | Allowed from | Result |

        | --- | --- | --- |

        | `deactivate` | active, suspended, locked | `deactivated`; workspace
        sessions end |

        | `suspend` | active | `suspended`; workspace sessions end |

        | `reactivate` | suspended, deactivated, locked | `active`; a sign-in
        lockout returns `409 LOCKED_BY_LOGIN_LOCKOUT` |

        | `reset_mfa` | active, locked | MFA enrolment cleared |

        | `revoke_sessions` | active, suspended, locked | workspace sessions
        end; status unchanged |

        | `resend_invite` | pending, expired | new invitation, expiry restarted
        |


        Any other combination returns `409 INVALID_STATE_TRANSITION`.


        **Required scope:** `workspace.members.write`
      operationId: runWorkspaceMemberAction
      parameters:
        - schema:
            type: string
            minLength: 1
          required: true
          name: workspaceId
          in: path
        - schema:
            type: string
            minLength: 1
          required: true
          name: memberId
          in: path
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  enum:
                    - deactivate
                    - suspend
                    - reactivate
                    - reset_mfa
                    - revoke_sessions
                    - resend_invite
                reason:
                  type: string
                  maxLength: 500
              required:
                - action
              additionalProperties: false
            example:
              action: suspend
              reason: Leave of absence
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    enum:
                      - true
                  data:
                    type: object
                    properties:
                      member:
                        $ref: '#/components/schemas/WorkspaceMember'
                      action:
                        type: string
                        enum:
                          - deactivate
                          - suspend
                          - reactivate
                          - reset_mfa
                          - revoke_sessions
                          - resend_invite
                      previousStatus:
                        type: string
                      warnings:
                        type: array
                        items:
                          type: string
                          enum:
                            - INVITE_EMAIL_QUEUED
                    required:
                      - member
                      - action
                      - previousStatus
                required:
                  - success
                  - data
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
      security:
        - platformApiKey: []
        - bearerPlatformKey: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 255
      description: >-
        Recommended on every write. A retry with the same key and body replays
        the first result instead of repeating the change. A different body
        returns `422 IDEMPOTENCY_KEY_REUSED`; a retry while the first is still
        running returns `409 IDEMPOTENCY_IN_PROGRESS`.
  schemas:
    WorkspaceMember:
      type: object
      required:
        - memberId
        - role
        - status
        - createdAt
        - updatedAt
        - revision
      properties:
        memberId:
          type: string
          example: 0193f1c2-7a4e-7b10-9c3d-5e6f7a8b9c0d
          description: Stable membership ID. Unchanged when an invitation is accepted.
        userId:
          type: string
          description: >-
            Present once the person has signed in; absent while pending or
            expired.
        email:
          type: string
          format: email
        name:
          type: string
        expiresAt:
          type: string
          format: date-time
          description: Invitation expiry. Present only while pending or expired.
        role:
          $ref: '#/components/schemas/RoleAssignment'
        externalId:
          type: string
          minLength: 1
          maxLength: 255
          description: >-
            Your identity system's ID for the person. Unique within the
            workspace.
        attributes:
          type: object
          additionalProperties:
            type: string
          description: Up to 50 string key–value pairs, 4 KB in total.
        assignmentSource:
          type: string
          example: api
          description: How the member was added, for example `api` or `invite`.
        status:
          $ref: '#/components/schemas/MemberStatus'
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        revision:
          type: integer
          minimum: 0
          description: >-
            Increases on every change. Returned as the weak `ETag`; send it in
            `If-Match`.
        projects:
          type: array
          items:
            $ref: '#/components/schemas/MemberProjectMembership'
          description: Present on get-member, or on list/search with `include=projects`.
        projectsTruncated:
          type: boolean
          description: True when `projects` was cut short.
    RoleAssignment:
      type: object
      description: >-
        A role held at one scope. Custom-role assignments are redacted: `roleId`
        and `name` are null and `type` is `custom`.
      required:
        - roleId
        - name
        - type
        - source
      properties:
        roleId:
          type: string
          nullable: true
          example: builtin.workspace.restricted_member
          description: >-
            Built-in role ID (`builtin.workspace.<role>` or
            `builtin.project.<role>`). Null for a custom role.
        name:
          type: string
          nullable: true
          example: RESTRICTED_MEMBER
        type:
          type: string
          enum:
            - system
            - custom
        source:
          type: string
          example: direct
          description: >-
            Always `direct` in v1. Clients must accept unknown values;
            `group:<groupId>` is reserved.
    MemberStatus:
      type: string
      enum:
        - pending
        - expired
        - active
        - suspended
        - deactivated
        - locked
      description: >-
        `pending` and `expired` are invitations and grant no access. `locked` is
        a system state (admin or sign-in lockout).
    MemberProjectMembership:
      type: object
      required:
        - id
        - role
      properties:
        id:
          type: string
          description: Project ID.
        name:
          type: string
        role:
          $ref: '#/components/schemas/RoleAssignment'
    Error:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: INSUFFICIENT_SCOPE
            message:
              type: string
            messages:
              type: array
              items:
                type: string
            retryable:
              type: boolean
            details:
              type: object
              additionalProperties: true
              description: >-
                Code-specific context, for example `requiredScope`,
                `currentStatus`, `reason` or `requestId`.
  headers:
    RequestId:
      description: Request ID. Quote it to Kore.ai Support.
      schema:
        type: string
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    BadRequest:
      description: >-
        Invalid request. Codes: `VALIDATION_ERROR`, `BATCH_EMPTY`,
        `BATCH_TOO_LARGE`, `DUPLICATE_IN_REQUEST`, `GROUPS_NOT_SUPPORTED`,
        `INVALID_CURSOR`, `INVALID_FILTER`, `INVALID_ACTION`,
        `NO_FIELDS_TO_UPDATE`, `INVALID_EXTERNAL_ID`,
        `ROLE_NOT_ASSIGNABLE_AT_SCOPE`.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: >-
        `UNAUTHORIZED`: the key is missing, unknown, expired or revoked, or a
        user session or SDK token was sent. `KEY_DISABLED`: the key was
        suspended because its owner was not reassigned within 14 days.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: >-
        Codes: `INSUFFICIENT_SCOPE` (`details.requiredScope`),
        `KEY_TYPE_NOT_ALLOWED`, `OWNER_NOT_GRANTABLE_BY_KEY`,
        `SENSITIVE_ROLE_NOT_GRANTABLE_BY_KEY`, `ROLE_ABOVE_CALLER_AUTHORITY`,
        `CANNOT_MODIFY_OWNER`, `CANNOT_REMOVE_OWNER`,
        `CANNOT_MODIFY_KEY_CREATOR`, `TARGET_ABOVE_CALLER_AUTHORITY`,
        `PROJECT_OWNER_IMMUTABLE`, `AZURE_WORKSPACE_MANAGEMENT_RESTRICTED`.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: >-
        Codes: `WORKSPACE_NOT_FOUND`, `PROJECT_NOT_FOUND`, `MEMBER_NOT_FOUND`,
        `PROJECT_MEMBER_NOT_FOUND`, `ROLE_NOT_FOUND`. Also returned for
        resources outside the key’s workspace.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: >-
        Codes: `INVALID_STATE_TRANSITION` (`details.currentStatus`),
        `MFA_NOT_ENROLLED`, `LOCKED_BY_LOGIN_LOCKOUT`,
        `ACCOUNT_SHARED_ACROSS_WORKSPACES`, `MEMBER_STATE_CONFLICT`,
        `ROLE_UNCHANGED`, `EXTERNAL_ID_CONFLICT`, `MEMBER_OWNS_RESOURCES`,
        `MEMBER_OWNS_TOO_MANY_RESOURCES`, `TRANSFER_TARGET_NOT_ELIGIBLE`,
        `IDEMPOTENCY_IN_PROGRESS`, `WORKSPACE_NOT_ACTIVE`, `PROJECT_ARCHIVED`.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: >-
        `IDEMPOTENCY_KEY_REUSED`: the `Idempotency-Key` was already used with a
        different body.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: >-
        `RATE_LIMITED` or `CONCURRENCY_LIMIT_EXCEEDED`. Wait for `Retry-After`
        seconds.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InternalError:
      description: >-
        `INTERNAL_ERROR`. Retry after a short delay; `details.requestId`
        identifies the request.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadGateway:
      description: >-
        `INVITE_EMAIL_FAILED`: the invitation was renewed but the email could be
        neither sent nor queued.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServiceUnavailable:
      description: >-
        `AUTH_UNAVAILABLE` or `DEPENDENCY_UNAVAILABLE`. A platform dependency is
        down; retry later.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    platformApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Platform key, for example `abl_ws_…`.
    bearerPlatformKey:
      type: http
      scheme: bearer
      bearerFormat: Platform API Key
      description: The same platform key as a bearer token.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.