---
title: "Grant a scope membership inside your own org (idempotent)"
method: POST
path: "/me/scope-memberships"
tags: ["scope-membership"]
---

# Grant a scope membership inside your own org (idempotent)

`POST /me/scope-memberships`

## Request

- Base URL: `https://api.getmetacognition.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getmetacognition.com/me/scope-memberships`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/me/scope-memberships/post.ts> (a function with typed inputs; its response is checked against the schema)

Grant a team:/project: scope to a user in your organization. The org comes from the token. Idempotent: replaying an existing grant returns 200, and a different role on replay updates the stored role. The grant applies from that user's next request.

## Request body

- ScopeMembershipGrant: Org-scoped grant request. Any `org_id` in the body is ignored.
  - `user_id` string, required: Application user ID
  - `scope_id` string, required: Canonical scope id "<kind>:<value>" (kinds: user/team/org/project)
  - `role` string: Role within the scope

## Response `201`

Successful Response

- ScopeMembershipMutationResponse
  - `membership` ScopeMembershipResponse, required: One membership row.
    - `id` integer, required
    - `org_id` string, required
    - `user_id` string, required
    - `scope_id` string, required
    - `role` string, required
    - `created_at` string, date-time, required
  - `created` boolean, required: False when the grant already existed (idempotent add)
  - `note` string: Propagation caveat

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/metacognition/apis/tex-api.md) - [All operations](https://skmtc.dev/metacognition/apis/tex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metacognition/apis/tex-api/revisions/3bef47e50f2e?raw)