---
title: "Add social link"
method: POST
path: "/v1/account/social-links"
tags: ["profiles"]
---

# Add social link

`POST /v1/account/social-links`

Add a social link to the authenticated user's profile.

Supported platforms: x, github, discord, farcaster, lens, telegram, youtube, substack, website,
instagram, linkedin, medium, reddit, soundcloud, tiktok, custom

- "twitter" is accepted and normalized to "x"
- Platform names are case-insensitive
- Only one link per platform per account is allowed (except "custom" — multiple allowed)
- Each social link URL is globally unique (first-come-first-serve)
- YouTube: accepts @handle or full channel URL, normalized to canonical URL
- Website: accepts domain or full URL, normalized to https://domain
- GitHub: accepts username or full URL, normalized to https://github.com/username

Note: Links are unverified by default. Verification support coming in a future release.

Authentication: `Authorization: Bearer <CLIENT_JWT>`

## Headers

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

## Request body

- SocialLinkRequest — Request model for POST /v1/account/social-links. For YouTube: accepts @handle or full channel URL. Normalized to canonical URL. For Website: accepts bare domain or full URL. Normalized to https://domain. For other platforms: requires a valid URL.
  - `platform` string, required — Platform name (x, twitter, github, youtube, website, etc.)
  - `url` string, required — URL, handle, or identifier for the social profile
  - `display_name` string, nullable — Optional display label for this link (e.g., 'Shop', 'Blog'). Useful for custom links.

## Response `200`

Successful Response

- SocialLinkResponse — Response model for social link operations.
  - `id` string, required — Identity ID for the social link
  - `platform` string, required — Platform name
  - `url` string, required — Full URL to the social profile
  - `verified` boolean — Whether ownership has been verified
  - `verified_at` string, nullable — When ownership was verified (ISO 8601)
  - `verification_method` string, nullable — How ownership was verified (e.g., oauth_youtube)
  - `created_at` string, required — When the link was added (ISO 8601)
  - `display_name` string, nullable — Display name from the platform profile

## Other responses

- `400` — Invalid platform or link already exists on this account
- `401` — Missing or invalid JWT
- `409` — Social link 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)