Organizations & usage

Invite a person, or change a member's role

PUT /api/v1/orgs/{org}/members/{user}

Invites a person or changes a member's role. The organization's owners only. Someone who isn't a member is invited, not added: the invite goes to their account's address, which the answer never shows, and waits in their inbox, and they join, at the role it offers, only when they accept it. A member's new role applies at once. Without a role, the invite is to be a member, and a member keeps their role. Inviting someone, or making a member an owner, needs a browser the caller signed in to with an email link, a passkey or a provider, or else their passkey on this request: a pending request returns a problem with next.action confirm and next.url; repeat it in the same client after confirming. For an owner, that browser must have signed in within the last 10 minutes. An organization always keeps at least one owner. A frozen organization cannot promote a member to owner; demotions remain available.

Parameters

orgpath · required · string: The organization, such as acme.
userpath · required · string: The person's handle, such as bob.

Example request

curl --request PUT 'https://commitscale.com/api/v1/orgs/acme/members/sam' \
  --header "Authorization: Bearer $CSCALE_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{}'

Example values illustrate the format. Use your own credentials and identifiers.

Request body

application/json

One of these shapes

May be null.

Invites a person to an organization, or updates a member's role. Without a role, the invite is to be a member, and a member keeps theirs.

roleoptional · owner / member: The person's role in the organization: owner or member.

Responses

200 The member, with their role.

application/json

{
  "added_at": "2026-10-26T10:00:00Z",
  "handle": "user:sam",
  "name": "sam",
  "role": "owner",
  "teams": []
}

added_atrequired · string (date-time): When the person became a member, in UTC.
handlerequired · string: user:bob.
namerequired · string: The member's public username.
rolerequired · owner / member: The person's role in the organization: owner or member.
teamsrequired · array of string: Reserved membership groups.
Fields of teams
Reserved membership groups.
Each item has this shape.

202 Invited: they join when they accept.

application/json

{
  "created_at": "2026-10-26T10:00:00Z",
  "email": "person@example.com",
  "expires_at": "2026-10-26T10:00:00Z",
  "id": 1,
  "invited_by": "user:alex",
  "org": "acme",
  "person": "user:alex"
}

An invite that waits for its person.

created_atrequired · string (date-time): When this record was created, in UTC.
emailoptional · string: The address it went to, for an invite sent to an address. An invite to someone by their handle never shows their address.
expires_atrequired · string (date-time): Its link works until then.
idrequired · integer (int64): Identifier used to accept, decline or withdraw the invitation.
invited_byrequired · string: Who sent it, such as user:john.
orgoptional · string: The organization's namespace name, such as acme.
personoptional · string: The person it is for, such as user:carol, for an invite sent to them by their handle.
roleoptional · owner / member: The person's role in the organization: owner or member.

RateLimit and RateLimit-Policy describe the request rate. Follow Retry-After when a response asks you to wait.

Problem responses

Errors use application/problem+json. Act on the stable code, and follow next when present. See the problem format.

organization_frozen403

The organization's Free plan has more than one person; members cannot write, nobody can promote an owner, and no check can start.

An owner can renew Pro or remove people until one remains; others can ask an owner.

organization_person_limit403

The organization's Free plan allows one person.

An owner can upgrade the organization to Pro, or ask an owner to do so.

check_key_scope403

A check-only key may call the test check, read its own usage and acceptance rule, contact support, and withdraw data sharing.

Use a person's sign-in for account management. More agent power needs the owner's passkey; this key cannot widen itself.

feature_off403

The namespace plan does not include this feature.

Retrying on the same plan will not help. GET /api/v1/namespaces/{namespace}/plan, and the namespace's Plan page in Settings, show what its plan includes.

unauthenticated401

The request carried no credentials.

Use this operation's sign-in method. Bearer credentials use Authorization: Bearer <token>; browser credentials use the session cookie.

invalid_token401

The token is unknown, expired, or revoked, its agent was revoked, or an OAuth token was used outside its MCP resource.

Stop using it. Sign in again, or ask the owner to create a replacement agent key.

forbidden403

The caller may not do this: only people may, only owners may, or the agent was not given this repository or write access.

Stop. Retrying will not help. Ask the owner for the access, or leave the step to a person.

not_found404

It does not exist, or the caller cannot read it: a repository the caller cannot read is reported as not found.

Check the name or ID, and that the token has the repository.

already_exists409

Something with that name exists, or its current state does not allow this request.

Use the one that exists, or choose another name.

conflict409

The request conflicts with the current state, such as a membership that changed since you read it.

Read detail, fetch the current state, and change the request. When retry_after_s is set, retrying the same request later can work.

invalid_request400 / 413 / 415 / 422

The request is malformed or breaks a rule, such as a title that is too long, or a body that is not the expected JSON.

Fix the request as detail says. The same request fails the same way.

quota_exceeded422 / 429

With 429, the caller used its requests for the minute. With 422, a count limit was reached.

With 429, wait Retry-After seconds and retry. With 422, remove one first.

internal500

The server failed, and logged why.

Retry after Retry-After seconds. A write is safe to retry with the same idempotency key.