The Canva Admin API is currently provided as a preview and is subject to change.

Update user

Updates a user that is already managed by the caller's organization. Only the fields passed in are updated; omitted fields are left unchanged. The name fields (display_name, first_name, last_name) are updated together — set first_name or last_name to an empty string to clear them (blank first and last names are allowed).

HTTP method and URL path

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

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 (permissions):

  • admin:user:write

Header parameters

Authorizationstring
Required

Provides credentials to authenticate the request, in the form of a Bearer token.

For example: Authorization: Bearer {token}

Content-Typestring
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

Path parameters

userIdstring
Required

The user ID.

Body parameters

nameUserNameUpdate
Optional

The name fields to update for the user.

display_namestring
Required

The display name of the user.

Minimum length: 1

first_namestring
Required

The first name of the user. Set to an empty string to clear the first name.

last_namestring
Required

The last name of the user. Set to an empty string to clear the last name.

localestring
Optional

The locale of the user, as an IETF BCP 47 language tag. Must be a supported language.

saml_accountSamlAccount
Optional

The SAML account details used to link the user to the organization's identity provider for SSO.

idp_issuerstring
Required

The issuer URL of the SAML identity provider. Must resolve to an identity provider owned by the caller's organization.

Minimum length: 1

name_idstring
Required

The SAML NameID that identifies the user to the identity provider. Case sensitive, should not change.

Minimum length: 1

Example request

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

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"
}
}'
SH
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));
JS
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());
}
}
JAVA
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())
PY
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);
};
CSHARP
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))
}
GO
$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;
}
PHP
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
RUBY

Success response

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

userUser

A user.

idstring

The user ID.

display_namestring
Optional

The display name of the user.

emailstring
Optional

The email address of the user.

first_namestring
Optional

The first name of the user.

last_namestring
Optional

The last name of the user.

last_active_atinteger
Optional

When the user was last active, as a Unix timestamp (in seconds since the Unix Epoch).

localestring
Optional

The locale of the user, as an IETF BCP 47 language tag.

rolestring
Optional

The role of the user in the organization.

Available values:

  • admin
  • brand_designer
  • member
saml_accountSamlAccount
Optional

The SAML account details used to link the user to the organization's identity provider for SSO.

idp_issuerstring

The issuer URL of the SAML identity provider. Must resolve to an identity provider owned by the caller's organization.

Minimum length: 1

name_idstring

The SAML NameID that identifies the user to the identity provider. Case sensitive, should not change.

Minimum length: 1

Example response

{
"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"
}
}
JSON

Error responses

400 Bad Request

codestring

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.

messagestring

A human-readable description of what went wrong.

Example error responses

The display name is not allowed
{
"code": "invalid_field",
"message": "The supplied display_name is not allowed."
}
JSON
The locale is not a supported language
{
"code": "invalid_field",
"message": "The locale {locale} is not a supported language."
}
JSON
The user is not managed by the organization
{
"code": "user_not_managed",
"message": "User {userId} is not managed by the organization"
}
JSON

403 Forbidden

codestring

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.

messagestring

A human-readable description of what went wrong.

Example error response

The SAML identity provider is not owned by the caller's organization (or doesn't exist)
{
"code": "permission_denied",
"message": "The identity provider is not owned by your organization."
}
JSON

409 Conflict

codestring

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.

messagestring

A human-readable description of what went wrong.

Example error responses

The SAML name ID is already in use
{
"code": "saml_name_id_not_available",
"message": "The SAML name ID {nameId} is already associated with another user."
}
JSON
{
"code": "user_pending_consent",
"message": "A previous request for this user is awaiting their consent. Wait for them to accept before retrying."
}
JSON