Skip to content
Karmo Developer Portal

Ensure membership exists for user in organization and assign roles

PUT
/auth/access-management/organizations/{organizationId}/users/{userId}/membership

Requires Authorization: Bearer in deployed environments. Mint the JWT through POST /auth/token with AWS SigV4 credentials. Creates the membership when missing. If it already exists, roles inside roleSet are replaced by roles while roles outside roleSet are preserved. Every role must be included in roleSet.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
userId
required
string
user_01J7C4Q8QABCD1234XYZ

Provider user identifier returned by createUser or listUsers.

organizationId
required
string
org_123

Provider tenant or organization identifier. In WorkOS mode this is the WorkOS organization id, for example org_123.

Request Body required

Section titled “Request Body required ”
object
roles
required

Role slugs to assign within the caller-managed roleSet. Every role must also appear in roleSet.

Array<string>
[
  "org-admin",
  "org-billing-manager"
]
roleSet
required

Caller-managed role scope. Existing membership roles outside this set are preserved; roles inside this set are replaced by the requested role selection.

Array<string>
[
  "org-admin",
  "org-billing-manager"
]

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Membership linked

object
organizationId
required

Provider tenant or organization identifier. In WorkOS mode this is the WorkOS organization id, for example org_123.

string
org_123
userId
required

Provider user identifier returned by createUser or listUsers.

string
user_01J7C4Q8QABCD1234XYZ
roles
required

Role slugs currently assigned to this user’s organization membership.

Array<string>
[
  "org-admin"
]
status

Current membership lifecycle status returned by the configured access provider.

string
Allowed values: active inactive pending 
active

400

Section titled “400 ”

BAD_REQUEST

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

401

Section titled “401 ”

UNAUTHORIZED

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

403

Section titled “403 ”

FORBIDDEN

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

404

Section titled “404 ”

NOT_FOUND

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

409

Section titled “409 ”

CONFLICT

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

422

Section titled “422 ”

UNPROCESSABLE_ENTITY

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

429

Section titled “429 ”

Configured access provider rate limited the request.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

500

Section titled “500 ”

INTERNAL_SERVER_ERROR

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email

503

Section titled “503 ”

Access-management provider is not configured for this environment.

object
type
required
string format: uri
title
required
string
status
required
integer
detail
string
instance
string
karmoCode
required

Karmo 8-digit error code.

string
/^[0-9]{8}$/
karmoMeta

Domain-level metadata emitted by the service.

object
key
additional properties
any
karmoErrors
Array<object>
object
detail
required

Human-readable detail for the specific field error.

string
pointer
required

JSON pointer to the offending value.

string
/email