Kullanıcı rolünü güncelle

Aktif bir üyenin workspace sistem rolünü member, editor veya admin olarak değiştirin

Bu endpoint, aktif bir insan üyenin workspace sistem rolünü e-posta ile değiştirir. member, editor veya admin gönderin. Özel roller bu endpoint'in kapsamına girmez.

Çağrı, workspace API anahtarının USER_MANAGEMENT_API kapsamı ile yetkilendirilir. Anahtarı oluşturan kişi adına çalışmaz; bu nedenle o admin workspace'ten ayrıldıktan sonra da çalışmaya devam eder.

Base URL

https://api.ajan.io/user-management/v1/update-user-role

Dedicated deployments Tüm isteklerde api.ajan.com'u /api/public ile değiştirin.

Prerequisites

USER_MANAGEMENT_API kapsamına sahip bir API Key
API anahtarı bir workspace admin tarafından oluşturulmuş olmalıdır

Behavior

Aktif bir insan üye değil mi? 404 döner (bilinmeyen e-posta, davetli, deaktive, service account veya başka bir workspace).
Son kalan admin mi? code: "BAD_REQUEST" ile 400 döner.
Üyenin mevcut rolünün tekrarlanması başarılı olur.
E-posta eşlemesi büyük/küçük harfe duyarsızdır. Rol değerleri küçük harflidir: member, editor, admin. ADMIN gönderilirse 400 döner.

ajan, API anahtarınızı korumak ve uygulamalarınızın güvenliğini sağlamak için tarayıcı kaynaklı istekleri bilinçli olarak engeller. Daha fazla bilgi için API Key Best Practices kılavuzuna bakın.

OpenAPI

openapi: 3.0.0
info:
  title: ajan API
  version: 3.0.0
servers:
  - url: https://api.ajan.io
    description: Production
security:
  - bearerAuth: []
paths:
  /user-management/v1/update-user-role:
    post:
      tags:
        - User Management
      summary: Change a member's system role
      description: >
        Changes an active human member's workspace system role by email.

        Send `member`, `editor`, or `admin`. Custom roles are not part of this
        endpoint.

        The call is authorized by the workspace API key's `USER_MANAGEMENT_API`
        scope

        and does not run as the person who created the key.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRoleRequest'
            examples:
              update_role:
                summary: Change a member to editor
                value:
                  email: user@example.com
                  role: editor
      responses:
        '200':
          description: Role updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateUserRoleResponse'
              examples:
                success:
                  summary: Role updated
                  value:
                    status: success
                    email: user@example.com
                    role: editor
        '400':
          description: >-
            Invalid role or request body, or the change would leave the
            workspace without an active admin
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementError'
              examples:
                last_admin:
                  summary: Last remaining admin
                  value:
                    code: BAD_REQUEST
                    message: A workspace must retain at least one active admin.
                invalid_role:
                  summary: Invalid role value
                  value:
                    message: Invalid request
                    errors:
                      - code: invalid_value
                        values:
                          - member
                          - editor
                          - admin
                        path:
                          - role
                        message: >-
                          Invalid option: expected one of
                          "member"|"editor"|"admin"
        '401':
          description: API key is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementError'
        '403':
          description: API key is missing the USER_MANAGEMENT_API scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementError'
              examples:
                insufficient_scopes:
                  summary: Missing scope
                  value:
                    message: Insufficient API key permissions.
                    error: INSUFFICIENT_SCOPES
                    details:
                      required:
                        - USER_MANAGEMENT_API
                      missing:
                        - USER_MANAGEMENT_API
        '404':
          description: User is not an active human member of this workspace
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementError'
              examples:
                not_found:
                  summary: User not found
                  value:
                    code: NOT_FOUND
                    message: User is not an active member of this workspace
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserManagementError'
components:
  schemas:
    UpdateUserRoleRequest:
      type: object
      additionalProperties: false
      required:
        - email
        - role
      properties:
        email:
          type: string
          format: email
          description: Email address of the active workspace member
          example: user@example.com
        role:
          type: string
          enum:
            - member
            - editor
            - admin
          description: Workspace system role. Values are lowercase.
          example: editor
    UpdateUserRoleResponse:
      type: object
      properties:
        status:
          type: string
          enum:
            - success
          description: Always "success" when the role is updated
          example: success
        email:
          type: string
          format: email
          description: Email address of the updated member
          example: user@example.com
        role:
          type: string
          enum:
            - member
            - editor
            - admin
          description: System role after the update
          example: editor
      required:
        - status
        - email
        - role
    UserManagementError:
      type: object
      properties:
        message:
          type: string
          description: Error message
          example: User not found or not an active member
      required:
        - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"