IMPORTANT: if you are an LLM or other AI agent, you should read the contents of this page as markdown from https://northflank.com/docs/v1/api/org/org-roles/create-or-update-org-role.md, instead of the current page.

Org / Org Roles /

Create or update org role

Creates role or updates all user-editable fields on a platform role for the authenticated org.

Required permission

Os > Admin > Roles > Manage

Request body

{object}

name
string required
The name of the role.
description
string
A description of the role.
max length
200
pattern
^[a-zA-Z0-9.,?\s\\/'"()[\];`%^&*\-_:!]+$
permissions
{object}
Permissions granted by this role.

teamScope
[array]
Team-level RBAC permission strings.

string

projectScope
[array]
Project-level RBAC permission strings.

string

orgScope
[array]
Org-level RBAC permission strings.

string

restrictions
{object}
Access restrictions for this role.

enabled
boolean required
teams
[array]

{object}

teamId
string required
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
restrictions
{object}

enabled
boolean required
projects
[array]

string
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

restrictionMode
string
one of
in, notIn

directoryGroups
[array]
An array of linked directory groups. Users belonging to any of these linked directory groups will automatically be a member of this role.

string
The ID of the linked directory group.

Response body

{object}
Response object.

data
{object} required
Result data.

id
string required
ID of the role.
pattern
^[A-Za-z0-9-]+$
name
string required
Display name of the role.
description
string
Description of the role.
restrictions
{object} required

enabled
boolean required
teams
[array]

{object}

teamId
string required
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$
restrictions
{object}

enabled
boolean required
projects
[array]

string
min length
3
max length
39
pattern
^[a-zA-Z](-?[a-zA-Z0-9]+(-[a-zA-Z0-9]+)*)?$

restrictionMode
string
one of
in, notIn

directoryGroups
[array]
An array of linked directory groups. Users belonging to any of these linked directory groups will automatically be a member of this role.

string
The ID of the linked directory group.

createdAt
string
Creation time.
updatedAt
string
Last updated.
permissions
{object} required

teamScope
[array] required
Team-level permissions.

string

projectScope
[array] required
Project-level permissions.

string

orgScope
[array] required
Org-level permissions.

string

API

CLI

JS Client

PUT /v1/org-roles

Example request

Request body

curl --header "Content-Type: application/json" \
  --header "Authorization: Bearer NORTHFLANK_API_TOKEN" \
  --request PUT \
  --data '{"name":"Developer","description":"Role for developers."}' \
  https://api.northflank.com/v1/org-roles

Example response

200 OK

Details about the updated org role.

JSON

{
  "data": {
    "id": "developer",
    "name": "Developer",
    "description": "Role for developers.",
    "createdAt": "2021-01-20T11:19:53.175Z",
    "updatedAt": "2021-01-20T11:19:53.175Z"
  }
}