Skip to main content
POST
/
v1beta1
/
roles
Create Role
curl --request POST \
  --url https://api.example.com/v1beta1/roles \
  --header 'Content-Type: application/json' \
  --data '
{
  "body": {
    "name": "<string>",
    "title": "<string>",
    "permissions": [
      {}
    ],
    "scopes": [
      {}
    ],
    "metadata": {}
  }
}
'
{
  "role": {
    "id": "<string>",
    "name": "<string>",
    "title": "<string>",
    "permissions": [
      {}
    ],
    "scopes": [
      {}
    ],
    "state": "<string>",
    "org_id": "<string>",
    "metadata": {},
    "created_at": "<string>",
    "updated_at": "<string>"
  }
}
Creates a platform-wide role that can be assigned to users across the entire Frontier instance. The role bundles multiple permissions together.

​
Body

​
body
object
required
Role definition

​
Response

​
role
object
The created role object
curl -X POST 'https://frontier.example.com/v1beta1/roles' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "body": {
      "name": "org_owner",
      "title": "Organization Owner",
      "permissions": [
        "app_organization_update",
        "app_organization_delete",
        "app_project_create"
      ],
      "scopes": ["organization"],
      "metadata": {
        "description": "Full access to organization resources"
      }
    }
  }'

​
Request Example

{
  "body": {
    "name": "org_owner",
    "title": "Organization Owner",
    "permissions": [
      "app_organization_update",
      "app_organization_delete",
      "app_project_create"
    ],
    "scopes": ["organization"],
    "metadata": {
      "description": "Full access to organization resources"
    }
  }
}

​
Response Example

{
  "role": {
    "id": "9f256f86-20ad-434e-b009-6d6dadec6aa9",
    "name": "org_owner",
    "title": "Organization Owner",
    "permissions": [
      "app_organization_update",
      "app_organization_delete",
      "app_project_create"
    ],
    "scopes": ["organization"],
    "state": "enabled",
    "org_id": "00000000-0000-0000-0000-000000000000",
    "metadata": {
      "description": "Full access to organization resources"
    },
    "created_at": "2023-06-07T05:39:56.961Z",
    "updated_at": "2023-06-07T05:39:56.961Z"
  }
}

​
Notes

  • All specified permissions are verified to exist before creating the role
  • Permission names are normalized to their full slug format (e.g., app_organization_update)
  • The role automatically creates relations between itself and each permission for both user and service user principals
  • An audit record is created documenting the role creation

Build docs developers (and LLMs) love

Get started for freeTalk to us