Create Role

Create a new role in your organization. Roles can be assigned resources and users to control access to cloud infrastructure.

Request

POST https://api.entryguard.io/api/v1/roles

Authentication

Requires a valid Bearer JWT token with ORG_ADMIN role.

Authorization: Bearer <access_token>

Request Body

{
  "name": "string",
  "description": "string",
  "maxSessionDurationHours": "integer"
}

Field	Type	Required	Description
name	string	Yes	Role name (must be unique within the organization)
description	string	No	Optional description of the role's purpose
maxSessionDurationHours	integer	No	Maximum session duration in hours for users with this role (overrides user defaults)

Response

Returns the created role object.

Response Schema

{
  "id": "uuid",
  "name": "string",
  "description": "string",
  "maxSessionDurationHours": "integer",
  "resourceIds": ["uuid"],
  "userIds": ["uuid"],
  "createdAt": "timestamp",
  "updatedAt": "timestamp"
}

Success Response

Status Code: 201 Created

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Backend Developers",
  "description": "Access to backend services and databases",
  "maxSessionDurationHours": 8,
  "resourceIds": [],
  "userIds": [],
  "createdAt": "2026-02-18T10:30:00Z",
  "updatedAt": "2026-02-18T10:30:00Z"
}

Error Responses

Status Code	Description
400 Bad Request	Invalid request body or duplicate role name
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	User does not have ORG_ADMIN role
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error occurred

Error Response Examples:

{
  "timestamp": "2026-02-18T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "name is required",
  "path": "/api/v1/roles"
}

{
  "timestamp": "2026-02-18T10:30:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "A role with name 'Backend Developers' already exists",
  "path": "/api/v1/roles"
}

Example

Request

curl -X POST https://api.entryguard.io/api/v1/roles \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Developers",
    "description": "Access to backend services and databases",
    "maxSessionDurationHours": 8
  }'

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Backend Developers",
  "description": "Access to backend services and databases",
  "maxSessionDurationHours": 8,
  "resourceIds": [],
  "userIds": [],
  "createdAt": "2026-02-18T10:30:00Z",
  "updatedAt": "2026-02-18T10:30:00Z"
}