Create an Account identity

POST

/portal/v1/accounts/{accountSlug}/identities

Authentication

Bearer Token Authorization
JWT access token

Request body

emailstring*
first_namestring*
last_namestring*
passwordstring
Initial password (8-64 chars). NIST SP 800-63B aligned — no composition rules. HaveIBeenPwned breach check runs server-side. Omit to create a passwordless identity (sign-in via SSO/social or forgot-password reset).
external_idstring
metadataany object
application_idstring
Optional Application ID. When present, a same-transaction AppMembership row is created so the identity can sign into the named App immediately. Omit to create an orphan identity in the directory — the admin can attach it to one or more Apps later.

Code samples

cURL

JavaScript

Python

curl -X POST "https://api.canopy.dev/portal/v1/accounts/{accountSlug}/identities" \
  -H "Authorization: Bearer $CANOPY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "password": "string",
    "external_id": "string",
    "metadata": {},
    "application_id": "string"
  }'

const response = await fetch("https://api.canopy.dev/portal/v1/accounts/{accountSlug}/identities", {
  method: "POST",
  headers: {
    "Authorization": "Bearer $CANOPY_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "email": "string",
    "first_name": "string",
    "last_name": "string",
    "password": "string",
    "external_id": "string",
    "metadata": {},
    "application_id": "string"
  }),
});

const data = await response.json();

import requests

response = requests.post(
    "https://api.canopy.dev/portal/v1/accounts/{accountSlug}/identities",
    headers={
    "Authorization": "Bearer $CANOPY_TOKEN",
    "Content-Type": "application/json"
    },
    json={
        "email": "string",
        "first_name": "string",
        "last_name": "string",
        "password": "string",
        "external_id": "string",
        "metadata": {},
        "application_id": "string",
    },
)

data = response.json()

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

func main() {
	payload := map[string]interface{}{
		"email": "string",
		"first_name": "string",
		"last_name": "string",
		"password": "string",
		"external_id": "string",
		"metadata": map[string]interface{}{},
		"application_id": "string",
	}
	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", "https://api.canopy.dev/portal/v1/accounts/{accountSlug}/identities", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "Bearer $CANOPY_TOKEN")
	req.Header.Set("Content-Type", "application/json")

	resp, _ := http.DefaultClient.Do(req)
	defer resp.Body.Close()
}

Responses

201 Creates an identity at the Account tier. When `application_id` is provided, a same-request AppMembership row is also created so the identity can sign into that App immediately. When `application_id` is omitted, the identity is created as an orphan in the directory — the admin can attach it to one or more Apps later via the membership endpoints. Distinct from the env-scoped identity create which forcibly attaches to the App in the URL.

{
  "id": "string",
  "email": "string",
  "first_name": "string",
  "last_name": "string",
  "avatar_url": "string",
  "external_id": "string",
  "metadata": {},
  "is_active": false,
  "email_verified": false,
  "email_verified_at": "2026-04-20T12:00:00.000Z",
  "locked_until": "2026-04-20T12:00:00.000Z",
  "password_changed_at": "2026-04-20T12:00:00.000Z",
  "app_membership_count": 0,
  "total_assignments": 0,
  "created_at": "2026-04-20T12:00:00.000Z",
  "app_memberships": [
    {
      "id": "string",
      "application_id": "string",
      "application_slug": "string",
      "application_name": "string",
      "status": "active",
      "created_at": "2026-04-20T12:00:00.000Z",
      "assignment_count": 0
    }
  ]
}

application/json

idstring*
emailstring*
first_namestring*
last_namestring*
avatar_urlstring
external_idstring
metadataany object
is_activeboolean*
email_verifiedboolean*
email_verified_atstring (date-time)
locked_untilstring (date-time)
When non-null and in the future, the identity is locked out from login attempts. Set by the progressive lockout policy on repeated failed logins.
password_changed_atstring (date-time)
app_membership_countnumber*
total_assignmentsnumber*
created_atstring (date-time)*
app_membershipsAccountIdentityAppMembershipDto[]*
Every active AppMembership for this identity, ordered by Application name. Each entry carries the App's slug + name so the drawer can render links without an additional lookup, plus the per-App assignment count.

400 Password rejected — appeared in a known data breach (HaveIBeenPwned check)

401 Invalid or expired token

403 This token is not authorized for this endpoint (wrong principal type — e.g., admin token on identity-only endpoint, or vice versa)

404 Application not found in this Account — cannot attach an identity to an Application outside its own Account

409 Email already exists in this Application

Returned object

The AccountIdentityDetailResponseDto object View all properties on this resource

On this page

GETList identities in Account
POSTBulk-create Account identities
GETGet directory counts for the Account
GETGet an Account identity
PATCHUpdate an Account identity profile
PATCHSet Account-wide is_active flag
POSTAdmin-trigger a password reset email
POSTRe-send email verification
GETList audit events for an Account identity
POSTAdd an identity to an Application (create AppMembership)
DELETERemove an identity from an Application (revoke AppMembership)