Create role binding

Create a role binding for exactly one principal: a user, a group, or an API key. Every reference is checked against the caller’s organization; an identical binding is written again, because bindings are never unique. Pass expiresAt to time-box the access: it stops granting at that moment on its own, without being revoked, and a date that has already passed answers 422 grant_expiry_in_past. The response always carries the new binding’s id; the names of its principal, role and scope may be absent on this response alone, and a follow-up read carries them. superseded by /api/grants, which answers the same rows as grants

POST /api/v1/role-bindings

Python

Python

import requests

url = "https://app.langwatch.ai/api/v1/role-bindings"

payload = { "scopeId": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

201

{
  "id": "<string>",
  "principal": {
    "type": "user",
    "id": "<string>",
    "name": "<string>"
  },
  "role": "ADMIN",
  "customRoleId": "<string>",
  "customRoleName": "<string>",
  "scopeType": "PROJECT",
  "scopeId": "<string>",
  "scopeName": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "expiresAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

Admin API key for organization-level operations (managing projects, API keys). Create one in Settings > API Keys or via POST /api/api-keys. Format: sk-lw-{id}_{secret}.

Body

application/json

role · enum<string> · required

Available options: ADMIN, MEMBER, VIEWER, CUSTOM

scopeType · enum<string> · required

Available options: PROJECT, TEAM, ORGANIZATION

scopeId · string · required

Minimum string length: 1

userId · string

Minimum string length: 1

groupId · string

Minimum string length: 1

apiKeyId · string

Minimum string length: 1

customRoleId · string

Minimum string length: 1

expiresAt · string<date-time>

Response

201 - application/json

Success

id · string · required

principal · object · required

Show child attributes

role · enum<string> · required

Available options: ADMIN, MEMBER, VIEWER, CUSTOM

customRoleId · string | null · required

customRoleName · string | null · required

scopeType · enum<string> · required

Available options: PROJECT, TEAM, ORGANIZATION

scopeId · string · required

scopeName · string | null · required

createdAt · string<date-time> · required

expiresAt · string<date-time> | null · required