Update User Role

Change an active member's workspace system role to member, editor, or admin

This endpoint 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. It does not run as the person who created the key, so it keeps working after that admin leaves the workspace.

Base URL

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

Prerequisites

API Key with the USER_MANAGEMENT_API scope
The API key must be created by a workspace admin

Behavior

Not an active human member? Returns 404 (unknown email, invited, deactivated, service account, or another workspace).
Last remaining admin? Returns 400 with code: "BAD_REQUEST".
Repeating the member's current role succeeds.
Email matching is case-insensitive. Role values are lowercase: member, editor, admin. ADMIN returns 400.

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"