> ## Documentation Index
> Fetch the complete documentation index at: https://www.canva.dev/docs/admin/llms.txt
> Use this file to discover all available pages before exploring further.

# Update user

Updates a user that is already managed by the caller's organization. Only the fields provided in the request are updated, and any omitted fields are left unchanged.

The `name` object fields (`display_name`, `first_name`, and `last_name`) must be updated together. To clear a first or last name, set it to an empty string. Blank first and last names are allowed.

## HTTP method and URL path

PATCH https\://api.canva.com/admin/v1/users/\{userId}

### Rate limit

This operation is rate limited to 1000 requests per minute for your app.

## Authentication and authorization

This endpoint requires a valid access token that was generated using client credentials.

### Scopes

The access token must have all the following [scopes](/docs/admin/appendix/scopes) (permissions):

* `admin:user:write`

## Header parameters

<Prop.List>
  <Prop name="Authorization" type="string" required>
    Provides credentials to authenticate the request, in the form of a `Bearer` token.

    For example: `Authorization: Bearer {token}`
  </Prop>

  <Prop name="Content-Type" type="string" required>
    Indicates the media type of the information sent in the request. This must be set to `application/json`.

    For example: `Content-Type: application/json`
  </Prop>
</Prop.List>

## Path parameters

<Prop.List>
  <Prop name="userId" type="string" required>
    The user ID.
  </Prop>
</Prop.List>

## Body parameters

<Prop.List>
  <Prop name="name" type="UserNameUpdate">
    The name fields to update for the user.

    <PillAccordion title={<>Properties of <strong>name</strong></>} defaultExpanded={true}>
      <Prop.List>
        <Prop name="display_name" type="string" required>
          The display name of the user.

          <Prop.Extras>
            **Minimum length:** `1`
          </Prop.Extras>
        </Prop>

        <Prop name="first_name" type="string" required>
          The first name of the user. Set to an empty string to clear the first name.
        </Prop>

        <Prop name="last_name" type="string" required>
          The last name of the user. Set to an empty string to clear the last name.
        </Prop>
      </Prop.List>
    </PillAccordion>
  </Prop>

  <Prop name="locale" type="string">
    The locale of the user, as an IETF BCP 47 language tag. Must be a supported language.
  </Prop>

  <Prop name="saml_account" type="SamlAccount">
    The SAML account details used to link the user to the organization's identity provider for SSO.

    <PillAccordion title={<>Properties of <strong>saml_account</strong></>} defaultExpanded={true}>
      <Prop.List>
        <Prop name="idp_issuer" type="string" required>
          The issuer id or entity id of the SAML identity provider. Often a unique URL, but not always. Must resolve to an identity provider owned by the caller's organization.

          <Prop.Extras>
            **Minimum length:** `1`
          </Prop.Extras>
        </Prop>

        <Prop name="name_id" type="string" required>
          The SAML NameID that identifies the user to the identity provider. This value is case sensitive, and shouldn't change.

          <Prop.Extras>
            **Minimum length:** `1`
          </Prop.Extras>
        </Prop>
      </Prop.List>
    </PillAccordion>
  </Prop>
</Prop.List>

## Example request

Examples for using the `/v1/users/{userId}` endpoint:

<Tabs storageKey="example.language" disableContentTransition>
  <Tab name="cURL">
    ```sh
    curl --request PATCH 'https://api.canva.com/admin/v1/users/{userId}' \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "name": {
        "display_name": "Joe Smith",
        "first_name": "Joe",
        "last_name": "Smith"
      },
      "locale": "en-GB",
      "saml_account": {
        "idp_issuer": "https://sso.acme.com/saml/metadata",
        "name_id": "joe.smith@acme.com"
      }
    }'
    ```
  </Tab>

  <Tab name="Node.js">
    ```js
    const fetch = require("node-fetch");

    fetch("https://api.canva.com/admin/v1/users/{userId}", {
      method: "PATCH",
      headers: {
        "Authorization": "Bearer {token}",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        "name": {
          "display_name": "Joe Smith",
          "first_name": "Joe",
          "last_name": "Smith"
        },
        "locale": "en-GB",
        "saml_account": {
          "idp_issuer": "https://sso.acme.com/saml/metadata",
          "name_id": "joe.smith@acme.com"
        }
      }),
    })
      .then(async (response) => {
        const data = await response.json();
        console.log(data);
      })
      .catch(err => console.error(err));
    ```
  </Tab>

  <Tab name="Java">
    ```java
    import java.io.IOException;
    import java.net.URI;
    import java.net.http.*;

    public class ApiExample {
        public static void main(String[] args) throws IOException, InterruptedException {
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.canva.com/admin/v1/users/{userId}"))
                .header("Authorization", "Bearer {token}")
                .header("Content-Type", "application/json")
                .method("PATCH", HttpRequest.BodyPublishers.ofString("{\"name\": {\"display_name\": \"Joe Smith\", \"first_name\": \"Joe\", \"last_name\": \"Smith\"}, \"locale\": \"en-GB\", \"saml_account\": {\"idp_issuer\": \"https://sso.acme.com/saml/metadata\", \"name_id\": \"joe.smith@acme.com\"}}"))
                .build();

            HttpResponse<String> response = HttpClient.newHttpClient().send(
                request,
                HttpResponse.BodyHandlers.ofString()
            );
            System.out.println(response.body());
        }
    }
    ```
  </Tab>

  <Tab name="Python">
    ```py
    import requests

    headers = {
        "Authorization": "Bearer {token}",
        "Content-Type": "application/json"
    }

    data = {
        "name": {
            "display_name": "Joe Smith",
            "first_name": "Joe",
            "last_name": "Smith"
        },
        "locale": "en-GB",
        "saml_account": {
            "idp_issuer": "https://sso.acme.com/saml/metadata",
            "name_id": "joe.smith@acme.com"
        }
    }

    response = requests.patch("https://api.canva.com/admin/v1/users/{userId}",
        headers=headers,
        json=data
    )
    print(response.json())
    ```
  </Tab>

  <Tab name="C#">
    ```csharp
    using System.Net.Http;

    var client = new HttpClient();
    var request = new HttpRequestMessage
    {
      Method = HttpMethod.Patch,
      RequestUri = new Uri("https://api.canva.com/admin/v1/users/{userId}"),
      Headers =
      {
        { "Authorization", "Bearer {token}" },
      },
      Content = new StringContent(
        "{\"name\": {\"display_name\": \"Joe Smith\", \"first_name\": \"Joe\", \"last_name\": \"Smith\"}, \"locale\": \"en-GB\", \"saml_account\": {\"idp_issuer\": \"https://sso.acme.com/saml/metadata\", \"name_id\": \"joe.smith@acme.com\"}}",
        Encoding.UTF8,
        "application/json"
      ),
    };

    using (var response = await client.SendAsync(request))
    {
      response.EnsureSuccessStatusCode();
      var body = await response.Content.ReadAsStringAsync();
      Console.WriteLine(body);
    };
    ```
  </Tab>

  <Tab name="Go">
    ```go
    package main

    import (
    	"fmt"
    	"io"
    	"net/http"
    	"strings"
    )

    func main() {
    	payload := strings.NewReader(`{
    	  "name": {
    	    "display_name": "Joe Smith",
    	    "first_name": "Joe",
    	    "last_name": "Smith"
    	  },
    	  "locale": "en-GB",
    	  "saml_account": {
    	    "idp_issuer": "https://sso.acme.com/saml/metadata",
    	    "name_id": "joe.smith@acme.com"
    	  }
    	}`)

    	url := "https://api.canva.com/admin/v1/users/{userId}"
    	req, _ := http.NewRequest("PATCH", url, payload)
    	req.Header.Add("Authorization", "Bearer {token}")
    	req.Header.Add("Content-Type", "application/json")

    	res, _ := http.DefaultClient.Do(req)
    	defer res.Body.Close()
    	body, _ := io.ReadAll(res.Body)
    	fmt.Println(string(body))
    }
    ```
  </Tab>

  <Tab name="PHP">
    ```php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.canva.com/admin/v1/users/{userId}",
      CURLOPT_CUSTOMREQUEST => "PATCH",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => array(
        'Authorization: Bearer {token}',
        'Content-Type: application/json',
      ),
      CURLOPT_POSTFIELDS => json_encode([
        "name" => [
          "display_name" => "Joe Smith",
          "first_name" => "Joe",
          "last_name" => "Smith"
        ],
        "locale" => "en-GB",
        "saml_account" => [
          "idp_issuer" => "https://sso.acme.com/saml/metadata",
          "name_id" => "joe.smith@acme.com"
        ]
      ])
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    if (empty($err)) {
      echo $response;
    } else {
      echo "Error: " . $err;
    }
    ```
  </Tab>

  <Tab name="Ruby">
    ```ruby
    require 'net/http'
    require 'uri'

    url = URI('https://api.canva.com/admin/v1/users/{userId}')
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true

    request = Net::HTTP::Patch.new(url)
    request['Authorization'] = 'Bearer {token}'
    request['Content-Type'] = 'application/json'
    request.body = <<REQUEST_BODY
    {
      "name": {
        "display_name": "Joe Smith",
        "first_name": "Joe",
        "last_name": "Smith"
      },
      "locale": "en-GB",
      "saml_account": {
        "idp_issuer": "https://sso.acme.com/saml/metadata",
        "name_id": "joe.smith@acme.com"
      }
    }
    REQUEST_BODY

    response = http.request(request)
    puts response.read_body
    ```
  </Tab>
</Tabs>

## Success response

If successful, the endpoint returns a `200` response with a JSON body with the following parameters:

<Prop.List>
  <Prop name="user" type="User" required mode="output">
    A user.

    <PillAccordion title={<>Properties of <strong>user</strong></>} defaultExpanded={true}>
      <Prop.List>
        <Prop name="id" type="string" required mode="output">
          The user ID.
        </Prop>

        <Prop name="display_name" type="string" mode="output">
          The display name of the user.
        </Prop>

        <Prop name="email" type="string" mode="output">
          The email address of the user.
        </Prop>

        <Prop name="first_name" type="string" mode="output">
          The first name of the user.
        </Prop>

        <Prop name="last_name" type="string" mode="output">
          The last name of the user.
        </Prop>

        <Prop name="last_active_at" type="integer" mode="output">
          When the user was last active, as a Unix timestamp (in seconds since the Unix Epoch).
        </Prop>

        <Prop name="locale" type="string" mode="output">
          The locale of the user, as an IETF BCP 47 language tag.
        </Prop>

        <Prop name="role" type="string" mode="output">
          The role of the user in the organization.

          <Prop.Extras>
            **Available values:**

            * `admin`
            * `brand_designer`
            * `member`
          </Prop.Extras>
        </Prop>

        <Prop name="saml_account" type="SamlAccount" mode="output">
          The SAML account details used to link the user to the organization's identity provider for SSO.

          <PillAccordion title={<>Properties of <strong>saml_account</strong></>}>
            <Prop.List>
              <Prop name="idp_issuer" type="string" required mode="output">
                The issuer id or entity id of the SAML identity provider. Often a unique URL, but not always. Must resolve to an identity provider owned by the caller's organization.

                <Prop.Extras>
                  **Minimum length:** `1`
                </Prop.Extras>
              </Prop>

              <Prop name="name_id" type="string" required mode="output">
                The SAML NameID that identifies the user to the identity provider. This value is case sensitive, and shouldn't change.

                <Prop.Extras>
                  **Minimum length:** `1`
                </Prop.Extras>
              </Prop>
            </Prop.List>
          </PillAccordion>
        </Prop>
      </Prop.List>
    </PillAccordion>
  </Prop>
</Prop.List>

## Example response

```json
{
  "user": {
    "id": "UAAAAAAAAA1",
    "display_name": "Joe Smith",
    "email": "joe@acme.com",
    "first_name": "Joe",
    "last_name": "Smith",
    "last_active_at": 1750300000,
    "locale": "en",
    "role": "admin"
  }
}
```

## Error responses

### 400 Bad Request

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/admin/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error responses

##### The display name is not allowed

```json
{
  "code": "invalid_field",
  "message": "The supplied display_name is not allowed."
}
```

##### The locale is not a supported language

```json
{
  "code": "invalid_field",
  "message": "The locale {locale} is not a supported language."
}
```

##### The user is not managed by the organization

```json
{
  "code": "user_not_managed",
  "message": "User {userId} is not managed by the organization"
}
```

### 403 Forbidden

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/admin/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error response

##### The SAML identity provider is not owned by the caller's organization (or doesn't exist)

```json
{
  "code": "permission_denied",
  "message": "The identity provider is not owned by your organization."
}
```

### 409 Conflict

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/admin/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error responses

##### The user is already linked to a different SAML identity provider

```json
{
  "code": "user_linked_to_another_idp",
  "message": "User {userId} already has a SAML account linked to a different identity provider."
}
```

##### The SAML name ID is already in use

```json
{
  "code": "saml_name_id_not_available",
  "message": "The SAML name ID {nameId} is already associated with another user."
}
```

##### The user is awaiting consent from a previous request

```json
{
  "code": "user_pending_consent",
  "message": "A previous request for this user is awaiting their consent. Wait for them to accept before retrying."
}
```