> **Source:** https://knowledge.leegality.com/sign-station/api/create-role
> **Site:** Leegality Knowledge Base — https://knowledge.leegality.com
> **About:** Leegality is a document execution platform covering eSigning, stamps, NeSL, workflows, and REST API integration.
> **Navigation:** Every article on this site has a plain-text version at `<article-url>.txt` (this format). To get an index of all articles with their `.txt` links, read: https://knowledge.leegality.com/llms.txt
> **AI Guide:** For instructions on how to navigate this knowledge base as an AI agent, read: https://knowledge.leegality.com/ai-readable.txt

---
# POST /api/v1/roles — Create new role

Creates new role for the current user's organization

**Authentication:** `X-Auth-Token` header required on every request.

## Request URL

```
POST https://app1.leegality.com/api/api/v1/roles
```

**Environments:**
- Production: `https://app1.leegality.com/api/api/v1/roles`
- Sandbox: `https://sandbox.leegality.com/api/api/v1/roles`

---

## Request Body

**Content-Type:** `application/json`

Role data to create

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `name` | string | Yes | Role name. E.g., "Admin", "User" etc. | — |
| `entitlementIds` | array\<string\> | No | Entitlement IDs to assign to the role | — |

### Sample Request

```json
{
  "name": "string",
  "entitlementIds": [
    "string"
  ]
}
```

---

## Responses

### 200 — Role created successfully

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `code` | string | No | Response code indicating success or failure | — |
| `message` | string | No | Response message providing additional information | — |
| `data` | RoleVO | No | See **RoleVO** below. | — |

#### RoleVO

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `id` | string | No | Role ID. This is configured during the role creation. | `b0af5f43-7f34-4ea4-867a-10115642f354` |
| `name` | string | No | Role name. E.g., "Admin", "User" etc. | `Admin` |
| `createdAt` | string | No | The date and time when the role was created | `2025-12-15T10:20:30Z` |
| `entitlements` | array\<EntitlementVO\> | No | See **EntitlementVO** below. | — |

##### EntitlementVO

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `id` | string | No | Entitlement ID. This is configured in the system and cannot be changed. | `3fa85f64-5717-4562-b3fc-2c963f66afa6` |
| `name` | string | No | Entitlement name. E.g., "DOCUMENT_SIGN","USER_MANAGEMENT" | `DOCUMENT_SIGN` |

### 400 — Invalid request data

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `code` | string | No | Top-level error code | `LE_ERR_SS_400` |
| `errors` | array\<ErrorDetailCreateRole400VO\> | No | List of error details See **ErrorDetailCreateRole400VO** below. | — |

#### ErrorDetailCreateRole400VO

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `message` | string | No | Detailed error message | `Invalid value for field [name], Role name is required` |
| `path` | string | No | API path that generated the error | `/api/v1/roles` |

### 401 — Unauthorized - Invalid or expired token

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `code` | string | No | Top-level error code | `LE_ERR_SS_401` |
| `errors` | array\<ErrorDetail401Unauthorized\> | No | List of error details See **ErrorDetail401Unauthorized** below. | — |

#### ErrorDetail401Unauthorized

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `message` | string | No | Detailed error message | `Invalid or expired token` |
| `path` | string | No | API path that generated the error | `/api/v1/*` |
| `code` | string | No | Specific error code | `LE_ERR_SS_303` |

### 409 — Role already exists

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `code` | string | No | Top-level error code | `LE_ERR_SS_409` |
| `errors` | array\<ErrorDetailCreateRole409VO\> | No | List of error details See **ErrorDetailCreateRole409VO** below. | — |

#### ErrorDetailCreateRole409VO

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `message` | string | No | Detailed error message | `Role with name 'TestRole' already exist.` |
| `path` | string | No | API path that generated the error | `/api/v1/roles` |
| `code` | string | No | Specific error code | `LE_ERR_SS_010` |

### 500 — Internal server error

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `code` | string | No | Top-level error code | `LE_ERR_SS_500` |
| `errors` | array\<ErrorDetailToken500VO\> | No | List of error details See **ErrorDetailToken500VO** below. | — |

#### ErrorDetailToken500VO

| Field | Type | Required | Description | Example |
|-------|------|----------|-------------|---------|
| `message` | string | No | Detailed error message | `Internal Server Error` |
| `path` | string | No | API path that generated the error | `null` |
| `code` | string | No | Specific error code | `null` |

### Sample Response (200)

```json
{
  "code": "string",
  "message": "string",
  "data": {
    "id": "b0af5f43-7f34-4ea4-867a-10115642f354",
    "name": "Admin",
    "createdAt": "2025-12-15T10:20:30Z",
    "entitlements": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "DOCUMENT_SIGN"
      }
    ]
  }
}
```