---
openapi: 3.0.3
info:
  title: Braze REST API – Update dashboard user account
  description: |
    ## Prerequisites

    To use this endpoint, you'll need a SCIM token. You'll use your service origin as the `X-Request-Origin` header. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning).

    ## Rate limit

    This endpoint has a rate limit of 20,000 requests per day, per company. This rate limit is shared with the `/scim/v2/Users/` GET, DELETE, and POST endpoints as documented in [API rate limits]({{site.baseurl}}/api/api_limits).
  version: 1.0.0
  contact:
    name: Braze Support
    url: https://www.braze.com/docs/braze_support/
  license:
    name: Braze Documentation
    url: https://www.braze.com/docs/api/home/
servers:
  - url: https://rest.iad-01.braze.com
    description: US-01
  - url: https://rest.iad-02.braze.com
    description: US-02
  - url: https://rest.iad-03.braze.com
    description: US-03
  - url: https://rest.iad-04.braze.com
    description: US-04
  - url: https://rest.iad-05.braze.com
    description: US-05
  - url: https://rest.iad-06.braze.com
    description: US-06
  - url: https://rest.iad-07.braze.com
    description: US-07
  - url: https://rest.iad-08.braze.com
    description: US-08
  - url: https://rest.us-10.braze.com
    description: US-10
  - url: https://rest.fra-01.braze.eu
    description: EU-01
  - url: https://rest.fra-02.braze.eu
    description: EU-02
  - url: https://rest.au-01.braze.com
    description: AU-01
  - url: https://rest.id-01.braze.com
    description: ID-01
  - url: https://rest.jp-01.braze.com
    description: JP-01
  - url: https://rest.kr-01.braze.com
    description: KR-01
security:
- BearerAuth: []
paths:
  /scim/v2/Users/{id}:
    put:
      summary: Update dashboard user account
      operationId: put_scim_v2_users_id_put_update_existing_user_account
      parameters:
        - name: id
          in: path
          required: true
          description: The user's resource ID. This parameter is returned by the `POST` `/scim/v2/Users/` or `GET` `/scim/v2/Users?filter=userName eq "user@example.com"` methods.
          schema:
            type: string
          example: dfa245b7-24195aec-887bb3ad-602b3340
        - name: X-Request-Origin
          in: header
          required: true
          description: 'Your service origin, sent as `X-Request-Origin: YOUR-REQUEST-ORIGIN-HERE`. For more information, refer to [Automated user provisioning]({{site.baseurl}}/scim/automated_user_provisioning).'
          schema:
            type: string
          example: YOUR-REQUEST-ORIGIN-HERE
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserAccountRequest'
            examples:
              with_permission_set:
                summary: Roles, workspace and team permissions, and a permission set
                value:
                  schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:User
                  name:
                    givenName: Test
                    familyName: User
                  department: finance
                  permissions:
                    companyPermissions:
                    - manage_company_settings
                    roles:
                    - roleName: Test Role
                    - roleId: 1f16c016-8e44-48f3-9fd7-2b8d5d70d9bd
                    appGroup:
                    - appGroupName: Test Workspace
                      appGroupPermissions:
                      - view_campaigns
                      - view_canvases
                      team:
                      - teamName: Test Team
                        teamPermissions:
                        - edit_campaigns
                        - launch_campaigns
                        - edit_canvases
                        - launch_canvases
                    - appGroupName: Other Test Workspace
                      appGroupPermissionSets:
                      - appGroupPermissionSetName: Test Permission Set
              with_workspace_permissions:
                summary: Roles, workspace permissions, and team permissions
                value:
                  schemas:
                  - urn:ietf:params:scim:schemas:core:2.0:User
                  name:
                    givenName: Test
                    familyName: User
                  department: finance
                  permissions:
                    companyPermissions:
                    - manage_company_settings
                    roles:
                    - roleName: Test Role
                    - roleId: 1f16c016-8e44-48f3-9fd7-2b8d5d70d9bd
                    appGroup:
                    - appGroupName: Test Workspace
                      appGroupPermissions:
                      - view_campaigns
                      - view_canvases
                      team:
                      - teamName: Test Team
                        teamPermissions:
                        - edit_campaigns
                        - launch_campaigns
                        - edit_canvases
                        - launch_canvases
      responses:
        "200":
          description: The request succeeded and the dashboard user account was updated. No action needed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardUser'
              examples:
                success:
                  summary: Dashboard user account updated
                  value:
                    schemas:
                    - urn:ietf:params:scim:schemas:core:2.0:User
                    id: dfa245b7-24195aec-887bb3ad-602b3340
                    userName: user@example.com
                    name:
                      givenName: Test
                      familyName: User
                    department: finance
                    lastSignInAt: 2024 Nov 11, 4:20 PM
                    createdAt: 2024 Nov 11, 4:20 PM
                    permissions:
                      companyPermissions:
                      - manage_company_settings
                      roles:
                      - roleName: Test Role
                        roleId: 7c9e6679-7425-40de-944b-e07fc1f90ae7
                        appGroup:
                        - appGroupId: a1b2c3d4-e5f6-4a1b-8c2d-3e4f5a6b7c8d
                          appGroupName: Some Workspace
                          appGroupPermissions:
                          - view_campaigns
                          - view_canvases
                          team:
                          - teamId: 1f16c016-8e44-48f3-9fd7-2b8d5d70d9bd
                            teamName: Some Team
                            teamPermissions:
                            - edit_campaigns
                            - launch_campaigns
                            - edit_canvases
                            - launch_canvases
                      - roleName: Another Test Role
                        roleId: b2c3d4e5-f6a7-4b1c-9d2e-4f5a6b7c8d9e
                        appGroup:
                        - appGroupId: c3d4e5f6-a7b8-4c1d-8e2f-5a6b7c8d9e0f
                          appGroupName: Production Workspace
                          appGroupPermissionSets:
                          - appGroupPermissionSetName: A Permission Set
                            appGroupPermissionSetId: d4e5f6a7-b8c9-4d1e-9f2a-6b7c8d9e0f1a
                            permissions:
                            - view_campaigns
                            - edit_campaigns
                            - view_content_blocks
                      appGroup:
                      - appGroupId: a1b2c3d4-e5f6-4a1b-8c2d-3e4f5a6b7c8d
                        appGroupName: Test Workspace
                        appGroupPermissions:
                        - view_campaigns
                        - view_canvases
                        team:
                        - teamId: 1f16c016-8e44-48f3-9fd7-2b8d5d70d9bd
                          teamName: Test Team
                          teamPermissions:
                          - edit_campaigns
                          - launch_campaigns
                          - edit_canvases
                          - launch_canvases
        "400":
          description: Bad request. The `permissions` object is invalid, such as an unknown permission, workspace, team, role, or permission set name. Correct the `permissions` object, then retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                unparsable:
                  summary: The request body violates the schema
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 400
                    detail: Request is unparsable, syntactically incorrect, or violates schema.
        "401":
          description: |
            Unauthorized. The SCIM bearer token is missing or invalid, the request origin isn't recognized, your IP isn't allowlisted, or SCIM isn't enabled. Send a valid SCIM bearer token from an allowlisted IP, and confirm SCIM provisioning is enabled. To enable SCIM, contact your Braze account manager.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_request_origin:
                  summary: The X-Request-Origin header is missing
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: X-Request-Origin header is missing.'
                invalid_token:
                  summary: The SCIM token isn't valid
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: token not valid.'
                ip_not_allowlisted:
                  summary: The request IP isn't allowlisted
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: Request IP is not in the configured IP allowlist.'
                scim_not_enabled:
                  summary: SCIM API access isn't enabled
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 401
                    detail: 'Unauthorized: SCIM API access is not enabled.'
        "404":
          description: |
            Not found. No user with this `id` exists in Braze. Confirm the user `id`, or find it with the [Search for existing dashboard users endpoint]({{site.baseurl}}/api/endpoints/scim/get_search_existing_dashboard_user/).

            If a user with this ID doesn't exist in Braze, the endpoint will respond with:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                user_not_found:
                  summary: User not found
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 404
                    detail: User resource (Braze Developer) not found
        "429":
          description: |
            Rate limited. You exceeded the SCIM daily rate limit of 20,000 requests per day. Slow your request rate and retry later. See [API rate limits]({{site.baseurl}}/api/api_limits/).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                over_rate_limit:
                  summary: Over rate limit
                  value:
                    schemas:
                    - urn:ietf:params:scim:api:messages:2.0:Error
                    status: 429
                    detail: You have exceeded your limit of 20000 requests per day. Please contact your account executive to increase your limit. If you do not have their info, you may contact Braze directly at https://www.braze.com/contact/.
        5XX:
          description: |
            Internal server error. An unexpected error occurred on the Braze server. Retry with exponential backoff. If the error persists, contact [Support]({{site.baseurl}}/braze_support/). The `detail` can be `cannot remove admin permissions from last company admin`, `a developer update is already in progress please try again.`, `an admin permission update is already in progress please try again.`, `failed to update permissions`, or `Failed to update user`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: SCIM token
      description: |
        SCIM endpoints authenticate with a SCIM token, not a REST API key. Generate the token in the
        Braze dashboard at **Settings → Company Settings → Admin Settings → SCIM Provisioning**.
        Pass the token as `Authorization: Bearer YOUR-SCIM-TOKEN-HERE`, and send your service
        origin in the `X-Request-Origin` header.
  schemas:
    UpdateUserAccountRequest:
      title: Update dashboard user account request
      type: object
      required: [schemas]
      properties:
        schemas:
          type: array
          items:
            type: string
          description: Expected SCIM 2.0 schema name for user object.
          example:
            - urn:ietf:params:scim:schemas:core:2.0:User
        name:
          allOf:
            - $ref: '#/components/schemas/UserName'
          description: This object contains the user's given name and family name. If omitted, the user's current name is left unchanged.
        department:
          type: string
          description: Valid department string from the [department string documentation]({{site.baseurl}}/api/objects_filters/scim_api_appendix). If omitted, the user's current department is left unchanged.
          example: finance
        permissions:
          allOf:
            - $ref: '#/components/schemas/Permissions'
          description: Permissions object as described in the [permissions object documentation]({{site.baseurl}}/api/objects_filters/scim_api_appendix). If omitted, the user's current permissions are left unchanged.
    DashboardUser:
      title: Dashboard user account
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
        id:
          type: string
        userName:
          type: string
        name:
          $ref: '#/components/schemas/UserName'
        department:
          type: string
        createdAt:
          type: string
        lastSignInAt:
          type: string
        permissions:
          $ref: '#/components/schemas/Permissions'
    TeamPermissions:
      title: Team permissions
      type: object
      properties:
        teamId:
          type: string
        teamName:
          type: string
        teamPermissions:
          type: array
          items:
            type: string
    PermissionSet:
      title: Permission set
      type: object
      properties:
        appGroupPermissionSetName:
          type: string
        appGroupPermissionSetId:
          type: string
        permissions:
          type: array
          items:
            type: string
    WorkspacePermissions:
      title: Workspace permissions
      type: object
      properties:
        appGroupId:
          type: string
        appGroupName:
          type: string
        appGroupPermissions:
          type: array
          items:
            type: string
        team:
          type: array
          items:
            $ref: '#/components/schemas/TeamPermissions'
        appGroupPermissionSets:
          type: array
          items:
            $ref: '#/components/schemas/PermissionSet'
    Role:
      title: Role
      type: object
      properties:
        roleName:
          type: string
        roleId:
          type: string
        appGroup:
          type: array
          items:
            $ref: '#/components/schemas/WorkspacePermissions'
    Permissions:
      title: Permissions
      type: object
      properties:
        companyPermissions:
          type: array
          items:
            type: string
        roles:
          type: array
          items:
            $ref: '#/components/schemas/Role'
        appGroup:
          type: array
          items:
            $ref: '#/components/schemas/WorkspacePermissions'
    UserName:
      title: Name
      type: object
      properties:
        givenName:
          type: string
          example: Test
        familyName:
          type: string
          example: User
    ErrorResponse:
      title: Error
      type: object
      properties:
        schemas:
          type: array
          items:
            type: string
          description: SCIM error message schema.
          example:
            - urn:ietf:params:scim:api:messages:2.0:Error
        status:
          type: integer
          description: The HTTP status code of the error.
          example: 404
        detail:
          type: string
          description: The error message describing why the request failed.
