---
title: "Accept Link"
method: POST
path: "/api/v2/account/join"
tags: ["Account"]
---

# Accept Link

`POST /api/v2/account/join`

## Request

- Base URL: `https://www.onlyworlds.com`
- URL: `https://www.onlyworlds.com/api/v2/account/join`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Session-Token`

A signed-in account accepts a person join link (the code after `#` in
an invite link) and becomes a member with the link's role. Body
`{"code": "ow_j_..."}`. A phone's `X-Session-Token` is credential enough.
Preview first with POST /api/v2/join/preview (no credential).

## Request body

- object
  - `code` string, required: The ow_j_ join code.

## Response `201`

Joined: the new membership (the same row as accepting an invite).

- object
  - `id` string, uuid, required: The membership.
  - `world_id` string, uuid, required
  - `world_name` string, required
  - `role` string, required
  - `joined_at` string, date-time, required
  - `roster_character` string, uuid, nullable, required: The member's Character in the world, or null.

## Other responses

- `401`: Missing or invalid account credential (Bearer ow_a_ token or session).
- `404`: The code is not valid: unknown, used, revoked or expired, or made for an AI agent rather than a person (not_found). One answer for every case; the code is not spent.
- `409`: Already a member (already_member). The code is not spent. No account PIN is needed to accept; a write key for the membership waits for one (pin_required).
- `422`: Invalid request: unknown or read-only field, bad value, unknown query parameter, over-long text, extensions over the size cap (invalid_request); `param` names the culprit.
- `429`: Too many requests: over the request budget (code too_many_requests, type rate_limited): 300 requests a minute per key or account token, 60 a minute per address for a request with neither. Retry after the Retry-After header's seconds.
- `503`: The server is busy: every request slot stayed full for 10 s (code server_busy, type api_error). Retry after the Retry-After header's seconds.

## Changes

- **2026-10-20** `78df39c4c62e`: 6 warning
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `401`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `404`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `409`
  - added the new `known_of_not_writable` enum value to the `error/code` response property for the response status `422`
  - …2 more
- **2026-10-20** `4dd5b1cd0687`: 12 warning
  - added the new `character_taken` enum value to the `error/code` response property for the response status `401`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `404`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `409`
  - added the new `character_taken` enum value to the `error/code` response property for the response status `422`
  - …8 more

[Operation history](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/changes/api/v2/account/join/post.md)

---

[API](https://skmtc.dev/onlyworlds/apis/onlyworlds-api.md) · [All operations](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/llms.txt) · [OpenAPI document](https://skmtc.dev/onlyworlds/apis/onlyworlds-api/revisions/1752622ae8ce?raw)