---
title: "Provision or look up a platform user"
method: POST
path: "/v1/platform/users/upsert"
tags: ["Platform"]
---

# Provision or look up a platform user

`POST /v1/platform/users/upsert`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/platform/users/upsert`
- Auth: HTTP bearer

Upserts a user using either an OIDC subject_token (verified against the platform app's JWKS) or an email address. Returns the user handle and connection ID.

## Request body

- UpsertPlatformUserRequest
  - `subject_token` string: OIDC JWT from the platform's IdP (verified against JWKS)
  - `subject_token_type` string: Token type for subject_token. Use `urn:1claw:params:oauth:token-type:siwe` with `siwe_message` and `siwe_signature` for wallet-based provisioning.
  - `email` string, email: Fallback when subject_token is not provided
  - `display_name` string
  - `siwe_message` string: EIP-4361 Sign-In With Ethereum message (required for SIWE upsert)
  - `siwe_signature` string: Hex-encoded SIWE signature (required for SIWE upsert)
  - `return_to` string, uri: Redirect URL after cross-org link consent
  - `create_sub_org` boolean: When true, creates a sub-org under the platform app's org
  - `app_id` string, uuid: Required only when calling as a user (the dashboard wizard). A `plt_` key carries its app in the credential; a user does not, so the app is named here and checked against the caller's org.

## Response `200`

Existing user found

- PlatformUserResponse
  - `user_handle` string, uuid
  - `is_new` boolean
  - `connection_id` string, uuid
  - `email` string
  - `link_required` LinkRequiredInfo
    - `status` 'link_required', required
    - `reason` string, required
    - `authorize_url` string, uri, required: OAuth authorize URL the platform app should redirect the user to for consent.
    - `app_slug` string, required

## Other responses

- `201`: New user created
- `409`: User exists in a different organization. Contains a link_required payload with an OAuth authorize URL for cross-org consent.

---

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