> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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, and an identical binding answers 409 role_binding_already_exists.



## OpenAPI

````yaml POST /api/role-bindings
openapi: 3.1.0
info:
  title: LangWatch API
  version: 1.0.0
  description: LangWatch openapi spec
servers:
  - url: https://app.langwatch.ai
security:
  - project_api_key: []
paths:
  /api/role-bindings:
    post:
      tags:
        - Role Bindings
      description: >-
        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,
        and an identical binding answers 409 role_binding_already_exists.
      operationId: createRoleBinding
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: string
                  minLength: 1
                groupId:
                  type: string
                  minLength: 1
                apiKeyId:
                  type: string
                  minLength: 1
                role:
                  type: string
                  enum:
                    - ADMIN
                    - MEMBER
                    - VIEWER
                    - CUSTOM
                customRoleId:
                  type: string
                  minLength: 1
                scopeType:
                  type: string
                  enum:
                    - ORGANIZATION
                    - TEAM
                    - PROJECT
                scopeId:
                  type: string
                  minLength: 1
              required:
                - role
                - scopeType
                - scopeId
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  principal:
                    type: object
                    properties:
                      type:
                        type: string
                        enum:
                          - user
                          - group
                          - apiKey
                      id:
                        type: string
                      name:
                        type:
                          - string
                          - 'null'
                    required:
                      - type
                      - id
                      - name
                  role:
                    type: string
                    enum:
                      - ADMIN
                      - MEMBER
                      - VIEWER
                      - CUSTOM
                  customRoleId:
                    type:
                      - string
                      - 'null'
                  customRoleName:
                    type:
                      - string
                      - 'null'
                  scopeType:
                    type: string
                    enum:
                      - ORGANIZATION
                      - TEAM
                      - PROJECT
                  scopeId:
                    type: string
                  scopeName:
                    type:
                      - string
                      - 'null'
                  createdAt:
                    type: string
                  hasLegacyAccessNotice:
                    type: boolean
                required:
                  - id
                  - principal
                  - role
                  - customRoleId
                  - customRoleName
                  - scopeType
                  - scopeId
                  - scopeName
                  - createdAt
      security:
        - admin_api_key: []
components:
  securitySchemes:
    project_api_key:
      type: apiKey
      in: header
      name: X-Auth-Token
      description: >-
        Project API key for sending traces and accessing project-scoped
        resources. Format: sk-lw-... (no underscore). Obtain one by creating a
        project via the Admin API or the LangWatch UI.
    admin_api_key:
      type: http
      scheme: bearer
      description: >-
        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}.

````