---
title: "Add organization user by ID"
method: POST
path: "/internal/v1/orgs/{org_id}/users"
tags: ["Users"]
---

# Add organization user by ID

`POST /internal/v1/orgs/{org_id}/users`

Create or update an OrgUser membership for an existing User. Idempotent: if the user is already a member, their role is updated to the supplied value. Used by automation that holds a userId directly. Requires org admin. Accepts users with email_confirmed=false (e.g. invited but not yet accepted).

## Path parameters

- `org_id` integer, required

## Request body

- OrgUserCreateRequest — Body for POST /orgs/{org_id}/users. Creates an OrgUser membership for an existing User by ID. Idempotent — re-posting the same userId updates the role.
  - `userId` integer, required — ID of an existing User to attach to the org.
  - `role` 'owner' | 'admin' | 'member' | 'viewer' | 'billing_manager' | 'collaborator', required — A user's role within an organization.

## Response `200`

Membership created or role updated.

- OrgUserCreateResponse — Response from POST /orgs/{org_id}/users. Wraps the created or updated OrgUser under `orgUser`.
  - `orgUser` OrgUser, required — An organization membership row. Links a user to an organization with a role.
    - `id` integer, required
    - `orgId` integer, required
    - `userId` integer, required
    - `providerId` integer — SSO provider ID if the membership was auto-provisioned via OIDC/SAML. Zero for memberships created directly or via invitation acceptance.
    - `role` 'owner' | 'admin' | 'member' | 'viewer' | 'billing_manager' | 'collaborator', required — A user's role within an organization.
    - `updatedAt` number — Unix timestamp in nanoseconds.

## Other responses

- `400` — Invalid request
- `401` — Authentication required
- `403` — Insufficient permissions
- `500` — Internal server error

---

[API](https://skmtc.dev/uptrace/apis/uptrace-json-api.md) · [All operations](https://skmtc.dev/uptrace/apis/uptrace-json-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/uptrace/uptrace-json-api/revisions/550c8881ab9a/schema)