---
title: "Claim a handle for your account"
method: POST
path: "/v1/account/handle"
tags: ["account"]
---

# Claim a handle for your account

`POST /v1/account/handle`

Claim a Twitter-style handle for your account.

Handle requirements:
- 3-15 characters
- Lowercase letters, numbers, and underscores only
- Cannot start or end with underscore
- Cannot have consecutive underscores
- Certain handles are reserved (admin, grove, support, etc.)

Authentication: `Authorization: Bearer <CLIENT_JWT>`

Notes:
- Each account can only have one handle at a time
- Handles must be globally unique
- To change your handle, release and re-claim via this endpoint. For atomic
  renames (no release-then-claim race window), use the admin-only
  `POST /admin/maintenance/change-handle` endpoint.

## Headers

- `authorization` string, nullable — Bearer JWT issued by Grove that identifies the account.

## Request body

- HandleClaimRequest — Request model for claiming a handle. Handles are Twitter-style usernames: - 3-15 characters - Lowercase letters, numbers, underscores only - Cannot start/end with underscore - Cannot have consecutive underscores - Certain handles are reserved (admin, grove, support, etc.)
  - `handle` string, required — Handle to claim (3-15 chars, lowercase alphanumeric + underscore)

## Response `200`

Successful Response

- HandleClaimResponse — Response model for successful handle claim.
  - `handle` string, required — The claimed handle (normalized)
  - `account_id` string, required — Account ID that owns the handle

## Other responses

- `400` — Invalid handle format
- `409` — Handle already claimed by another account
- `422` — Validation Error

---

[API](https://skmtc.net/grove/apis/grove-api.md) · [All operations](https://skmtc.net/grove/apis/grove-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/grove/grove-api/revisions/f286b48a8105/schema)