Identities

Identities

Manage mock identities for the Identity Provider — new in SDK v1.2.0. For what identities are and how they behave in the OAuth flow, see Clients & Identities.

Create Identity

Create a mock identity linked to one of your mailboxes.

identity = client.create_identity(
    client_id="mc_EXAMPLECLIENTID",
    mailbox_address="tricia@minutemail.cc",
    username="tricia",
    name="Tricia McMillan",
    avatar_url="https://example.com/avatar.png",
    email_verified=False,          # Test the "unverified email" branch
    claims={"roles": "admin"}      # Custom claims merged into ID tokens
)

print(f"Identity: {identity['id']}")

Parameters

Parameter	Type	Required	Description
client_id	str	✅	OAuth client the identity belongs to
mailbox_address	str	✅	One of your active mailbox addresses
username	str	❌	Defaults to the local part of the mailbox address
name	str	❌	Display name; defaults to the username
avatar_url	str	❌	Picture URL returned by userinfo
email_verified	bool	❌	email_verified claim in ID tokens and userinfo (default True)
claims	dict	❌	Custom string-to-string claims merged into ID tokens and userinfo (default {}) — custom-provider clients only; rejected with a 400 for google/github/apple/facebook clients

Reserved claim names (iss, sub, aud, exp, iat, nbf, jti, email, email_verified, name, preferred_username, picture, nonce, at_hash) and empty claim keys are rejected by the API with a 400.

Returns

{
    "id": "ident_01JEXAMPLE",
    "clientId": "mc_EXAMPLECLIENTID",
    "mailboxAddress": "tricia@minutemail.cc",
    "username": "tricia",
    "name": "Tricia McMillan",
    "avatarUrl": "https://example.com/avatar.png",
    "isActive": True,
    "emailVerified": False,
    "claims": {"roles": "admin"}
}

---

Update Identity

Partially update an identity. Only the fields you pass are changed; client_id and mailbox_address are immutable.

identity = client.update_identity(
    "ident_01JEXAMPLE",
    name="Tricia McMillan",
    email_verified=True,
    claims={"roles": "admin", "tenant": "acme"}
)

Parameters

Parameter	Type	Required	Description
identity_id	str	✅	Identity identifier
username	str	❌	New username
name	str	❌	New display name
avatar_url	str	❌	New picture URL
is_active	bool	❌	False deactivates the identity — it is then skipped by the consent screen
email_verified	bool	❌	New email-verification status
claims	dict	❌	Replaces the existing claims wholesale when provided — custom-provider clients only (rejected with a 400 for google/github/apple/facebook clients)

Returns the updated identity, in the same shape as Create Identity.

For the email-verification and custom-claims testing patterns, see Testing email verification and custom claims. Custom claims are a custom-provider feature — Provider Behavior explains the per-provider restrictions.