v1

latestOpenAPI 3.1.02026-07-13143194365.4 KB
claim

Claim a reserved account via GitHub OAuth

Claim ownership of a pre-registered (reserved) Grove account by proving control of an attached GitHub identity via OAuth.

Flow:

  1. The user obtains a GitHub OAuth access token client-side
  2. The user submits the token here along with the Grove handle they want to claim
  3. The server validates the token against GitHub's API
  4. If the resolved GitHub identity matches an unverified GitHub identity attached to the reserved account, the account is transitioned to CLAIMED and a Grove session is issued.

Enumeration defense: all account-state failures (handle not found, organic account, already-claimed account, OAuth identity doesn't match any unverified identity on the account, malformed account) return the same generic 404. An attacker who has a valid OAuth token cannot use this endpoint to enumerate which Grove handles are reserved.

Token errors (invalid/expired OAuth token, platform API unavailable) propagate as 400/502 from the underlying OAuth validator — these are user-actionable and don't leak any account state.

The endpoint is rate-limited per client IP (independent from the claim lookup limiter).

post/v1/account/claim/social/github

Request body

handlestring required

Grove handle of the reserved account being claimed (case-insensitive)

access_tokenstring required

Platform OAuth access token obtained client-side

Example request

{
  "handle": "alice"
}

Response

Successful Response

account_idstring required

Account ID

api_keystring required

Grove API key (JWT)

identity_typestring required

Primary identity type

identity_valuestring required

Primary identity value

tipping_addressstring required

Server wallet address (for tipping)

onchain_addressstring required