Skip to main content

Identity API

The Identity namespace provides operations for managing identities, profiles, and usernames.

See Identities concept doc for product-level details.

Key Endpoints​

Get identity - GET /identity/{id}

Retrieve an identity. Currently only supports id='current' to get your own identity.

GET /identity/current

Update profile - PUT /identity/{id}

Replace profile fields (name, description, avatar, banner, background).

PUT /identity/current
{
  "id": "current",
  "displayName": "Alice",
  "description": "Building cool things",
  "avatarId": "media_abc123"
}

Set username - PUT /identity/{id}/username

Claim or change username.

PUT /identity/current/username
{
  "id": "current",
  "username": "alice"
}

Check username availability - GET /identity/username/{username}/status

Check if a username is available before attempting to claim it.

GET /identity/username/alice/status
# Returns: { "status": "available" | "in-use" | "invalid" }

Common Workflows​

View Your Profile​

GET /identity/current

Returns your identity with current profile, username, and DID.

Update Your Profile​

  1. Upload media (if adding avatar/banner): POST /media (see Media API)
  2. Update profile with media IDs:
PUT /identity/current
{
  "id": "current",
  "displayName": "New Name",
  "avatarId": "media_xyz"
}

Change Username​

  1. Check if username is available:
GET /identity/username/new-username/status
  1. Set username if available:
PUT /identity/current/username
{
  "id": "current",
  "username": "new-username"
}

Username must be unique, alphanumeric with hyphens/underscores.

Authorization​

  • Viewing your own identity: Always allowed (use id='current')
  • Viewing others: Not currently supported (only id='current' works)
  • Updating: Only your own identity
  • Username changes: Allowed at any time if username is available

See Also​