Platform

Provision or look up a platform user

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.

post/v1/platform/users/upsert

Request

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

Request body

subject_tokenstring

OIDC JWT from the platform's IdP (verified against JWKS)

subject_token_typestring

Token type for subject_token. Use urn:1claw:params:oauth:token-type:siwe with siwe_message and siwe_signature for wallet-based provisioning.

emailstring email

Fallback when subject_token is not provided

display_namestring
siwe_messagestring

EIP-4361 Sign-In With Ethereum message (required for SIWE upsert)

siwe_signaturestring

Hex-encoded SIWE signature (required for SIWE upsert)

return_tostring uri

Redirect URL after cross-org link consent

create_sub_orgboolean

When true, creates a sub-org under the platform app's org

app_idstring 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

Existing user found

user_handlestring uuid
is_newboolean
connection_idstring uuid
emailstring

Example response

{
  "link_required": {
    "reason": "user_exists_in_other_org"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.