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

# Assign a role to a subject

> Grants the role to a user, an identity-provider group, an email domain, or a service token.
Assignments cannot be edited: to move a subject to a different role, delete the assignment and create a new one.




## OpenAPI

````yaml api-reference/rbac/openapi.yaml POST /roles/{roleSrn}/create-assignment
openapi: 3.0.3
info:
  title: StarTree RBAC Manager API
  description: >
    Manage role-based access control (RBAC) in StarTree Cloud: policies, roles,
    the policies attached to each

    role, the subjects (users, groups, domains, service tokens) assigned to each
    role, and service tokens.


    Every request needs an `Authorization: Bearer <token>` header. See

    [Generating an API
    Token](/corecapabilities/security/manage-api-tokens#generating-an-api-token).


    Resources are identified by StarTree Resource Names (SRNs), for example
    `srn2:policy#my-policy` or

    `srn2:role#table-reader`. When an SRN appears in a URL path, encode the `#`
    as `%23`

    (`/policies/srn2:policy%23my-policy`).


    For a guided walkthrough of these endpoints, see

    [Using the RBAC API](/corecapabilities/security/using-rbac-api).
  version: '1.0'
servers:
  - url: '{baseUrl}/api/v1/rbac-manager'
    variables:
      baseUrl:
        default: https://rbac-manager.your-env.startree.cloud
        description: >-
          RBAC Manager URL of your StarTree Cloud environment without a trailing
          slash, e.g. https://rbac-manager.<env>.startree.cloud
security:
  - bearerAuth: []
tags:
  - name: Policies
    description: >-
      Create, list, update, and delete policies. A policy document says which
      actions are allowed or denied on which resources.
  - name: Roles
    description: >-
      Create, list, update, and delete roles. A role groups one or more
      policies.
  - name: Role policies
    description: Attach policies to roles and inspect what a role grants.
  - name: Role assignments
    description: Grant a role to users, groups, email domains, or service tokens.
  - name: Service tokens
    description: >-
      Bearer tokens for programmatic access. A token is unusable until it is
      assigned a role.
  - name: Access simulation
    description: >-
      Check what a subject would be allowed to do, before or after saving a
      policy.
paths:
  /roles/{roleSrn}/create-assignment:
    parameters:
      - $ref: '#/components/parameters/roleSrn'
    post:
      tags:
        - Role assignments
      summary: Assign a role to a subject
      description: >
        Grants the role to a user, an identity-provider group, an email domain,
        or a service token.

        Assignments cannot be edited: to move a subject to a different role,
        delete the assignment and create a new one.
      operationId: createRoleAssignment
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRoleAssignmentRequest'
            examples:
              user:
                summary: Assign to a user
                value:
                  subject: jane.doe@example.com
                  subjectType: user-email
              group:
                summary: Assign to an IdP group
                value:
                  subject: data-analysts
                  subjectType: group
              domain:
                summary: Assign to an email domain
                value:
                  subject: example.com
                  subjectType: domain
              serviceToken:
                summary: Assign to a service token
                value:
                  subject: a1B2c3D4e5F6g7H8
                  subjectType: service-token
      responses:
        '200':
          description: Role assigned. The response body is empty.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    roleSrn:
      name: roleSrn
      in: path
      required: true
      description: SRN of the role, with `#` encoded as `%23`.
      schema:
        type: string
      example: srn2:role%23table-reader-role
  schemas:
    CreateRoleAssignmentRequest:
      type: object
      required:
        - subject
        - subjectType
      properties:
        subject:
          type: string
          description: >-
            The user email, group name, domain, or service token access key,
            depending on `subjectType`.
          example: jane.doe@example.com
        subjectType:
          $ref: '#/components/schemas/SubjectType'
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Optional key-value metadata stored with the assignment.
    SubjectType:
      type: string
      description: >
        - `user-email`: an individual user's email address.

        - `group`: the name of a group in your identity provider.

        - `domain`: an email domain, such as `example.com`.

        - `service-token`: a service token, identified by its access key (the 16
        characters between `st-` and the next `-`).
      enum:
        - user-email
        - group
        - domain
        - service-token
    Error:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
          example: 404
        error:
          type: string
          example: Not Found
        message:
          type: string
          example: Not Found.
        path:
          type: string
          example: /api/v1/rbac-manager/policies/srn2:policy%23missing
  responses:
    BadRequest:
      description: >-
        The request body is missing a required field or refers to a resource
        that does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The caller's roles do not allow this RBAC operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No resource with the given SRN.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 404
            error: Not Found
            message: Not Found.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: A StarTree API token or a service token (`st-<accessKey>-<secretKey>`).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.