Authentication
All identity endpoints require authentication via therequireAuth middleware. Include a valid session token in your request.
Get All Identities
Retrieve all identities associated with the authenticated user.Response
Array of identity objects
Unique identifier for the identity
The display name of the identity (1-64 characters)
Unique handle for the identity (3-32 characters, alphanumeric and underscore only)
Optional email address associated with the identity
Optional birthday in string format
Optional URL for the identity’s avatar image
Optional URL or hex color (e.g., #FF6B6B) for the identity’s banner
Whether this is the user’s primary identity
Timestamp of when the identity was created
Get Single Identity
Retrieve a specific identity by ID. The identity must belong to the authenticated user.Path Parameters
The unique identifier of the identity to retrieve
Response
Identity object with the following fields:
Unique identifier for the identity
The display name of the identity
Unique handle for the identity
Email address associated with the identity
Birthday in string format
URL for the identity’s avatar image
URL or hex color for the identity’s banner
Whether this is the user’s primary identity
Timestamp of when the identity was created
Error Responses
404- Identity not found or does not belong to the authenticated user
Create Identity
Create a new identity for the authenticated user. Users can have a maximum of 5 identities.Request Body
Display name for the identity (1-64 characters)
Unique handle for the identity (3-32 characters, alphanumeric and underscore only). Will be converted to lowercase.
Optional email address (must be valid email format)
Optional birthday in string format
Optional URL for the identity’s avatar image (must be valid URL)
Optional URL or hex color (e.g., #FF6B6B) for the identity’s banner
Response
The created identity object
Unique identifier for the created identity
The display name of the identity
Unique handle (lowercase)
Email address
Birthday
Avatar URL
Banner URL or hex color
Whether this is the primary identity (true if it’s the user’s first identity)
Error Responses
400- Maximum of 5 identities allowed400- Handle is already taken400- Validation error (invalid format)
Activity Log
Creating an identity logs anidentity_created action with severity info.
Update Identity
Update an existing identity. All fields are optional.Path Parameters
The unique identifier of the identity to update
Request Body
Display name for the identity (1-64 characters)
Unique handle for the identity (3-32 characters, alphanumeric and underscore only)
Email address (set to null to remove)
Birthday (set to null to remove)
Avatar URL (set to null to remove)
Banner URL or hex color (set to null to remove)
Response
The updated identity object with all current fields
Error Responses
404- Identity not found or does not belong to the authenticated user400- Handle is already taken (when changing handle to one that exists)400- Validation error
Activity Log
Updating an identity logs anidentity_updated action with severity info.
Set Primary Identity
Set a specific identity as the user’s primary identity. This removes the primary status from all other identities.Path Parameters
The unique identifier of the identity to set as primary
Response
Returns true if the operation was successful
Error Responses
404- Identity not found or does not belong to the authenticated user
Delete Identity
Delete an identity. Cannot delete the primary identity or the user’s only identity.Path Parameters
The unique identifier of the identity to delete
Response
Returns true if the deletion was successful
Error Responses
404- Identity not found or does not belong to the authenticated user400- Cannot delete primary identity (set another identity as primary first)400- Cannot delete your only identity
Activity Log
Deleting an identity logs anidentity_deleted action with severity warning.