<!-- llms.txt: https://workos.com/llms.txt -->

# Environment role

An environment role is an access control resource defined at the environment level. Environment roles can be assigned to [organization memberships](https://workos.com/docs/reference/authkit/organization-membership), [directory users](https://workos.com/docs/directory-sync/identity-provider-role-assignment), and [SSO profiles](https://workos.com/docs/sso/identity-provider-role-assignment).

Environment roles provide a consistent set of roles across all organizations in your environment. Each role has a unique slug identifier. Roles can have permissions assigned to them.

## Add a permission to an environment role

Add a single permission to an environment role. If the permission is already assigned to the role, this operation has no effect.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/authorization/roles/admin/permissions" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "slug": "reports:export"
    }
BODY
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const role = await workos.authorization.addRolePermission('editor', {
  permissionSlug: 'documents:delete',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.add_environment_role_permission(
  slug: "admin",
  body_slug: "reports:export"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.add_environment_role_permission(
    slug="admin", body_slug="reports:export"
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().AddEnvironmentRolePermission(context.Background(), "admin", &workos.AuthorizationAddEnvironmentRolePermissionParams{
		Slug: "reports:export",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->authorization()
    ->addEnvironmentRolePermission(slug: "admin", bodySlug: "reports:export");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.authorization.AuthorizationApi.AddEnvironmentRolePermissionOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

AddEnvironmentRolePermissionOptions options =
    AddEnvironmentRolePermissionOptions.builder().slug("reports:export").build();

workos.authorization.addEnvironmentRolePermission("admin", options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.AddEnvironmentRolePermissionAsync("admin",
                                                             new AuthorizationAddEnvironmentRolePermissionOptions {
                                                                 Slug = "reports:export",
                                                             });
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::authorization::AddEnvironmentRolePermissionParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .add_environment_role_permission(
            "admin",
            AddEnvironmentRolePermissionParams {
                slug: "reports:export".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "slug": "admin",
  "object": "role",
  "id": "role_01EHQMYV6MBK39QC5PZXHY59C3",
  "name": "Admin",
  "description": "Can manage all resources",
  "type": "EnvironmentRole",
  "resource_type_slug": "organization",
  "permissions": [
    "reports:export"
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Create an environment role

Create a new environment role.

The `slug` must be unique across all environment roles and can only contain lowercase letters, numbers, hyphens, and underscores.

> **Note:** New roles are placed at the bottom of the priority order.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request POST \
  --url "https://api.workos.com/authorization/roles" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "slug": "editor",
        "name": "Editor",
        "description": "Can edit resources"
    }
BODY
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const role = await workos.authorization.createRole({
  slug: 'editor',
  name: 'Editor',
  description: 'Can edit and publish content',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.create_environment_role(
  slug: "editor",
  name: "Editor"
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.create_environment_role(slug="editor", name="Editor")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().CreateEnvironmentRole(context.Background(), &workos.AuthorizationCreateEnvironmentRoleParams{
		Slug: "editor",
		Name: "Editor",
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->authorization()->createEnvironmentRole(slug: "editor", name: "Editor");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.authorization.AuthorizationApi.CreateEnvironmentRoleOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

CreateEnvironmentRoleOptions options =
    CreateEnvironmentRoleOptions.builder().slug("editor").name("Editor").build();

workos.authorization.createEnvironmentRole(options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.CreateEnvironmentRoleAsync(new AuthorizationCreateEnvironmentRoleOptions {
    Slug = "editor",
    Name = "Editor",
});
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::authorization::CreateEnvironmentRoleParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .create_environment_role(
            CreateEnvironmentRoleParams {
                slug: "editor".into(),
                name: "Editor".into(),
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "slug": "editor",
  "object": "role",
  "id": "role_01EHQMYV6MBK39QC5PZXHY59C3",
  "name": "Editor",
  "description": "Can edit resources",
  "type": "EnvironmentRole",
  "resource_type_slug": "organization",
  "permissions": [
    "posts:read",
    "posts:write"
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Get an environment role

Get an environment role by its slug.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/authorization/roles/admin" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const role = await workos.authorization.getRole('admin');
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.get_environment_role(slug: "admin")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.get_environment_role(slug="admin")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().GetEnvironmentRole(context.Background(), "admin")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->authorization()->getEnvironmentRole(slug: "admin");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.authorization.getEnvironmentRole("admin");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.GetEnvironmentRoleAsync("admin");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .get_environment_role("admin")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "slug": "admin",
  "object": "role",
  "id": "role_01EHQMYV6MBK39QC5PZXHY59C3",
  "name": "Admin",
  "description": "Can manage all resources",
  "type": "EnvironmentRole",
  "resource_type_slug": "organization",
  "permissions": [
    "posts:read",
    "posts:write"
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## List environment roles

List all environment roles in priority order.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/authorization/roles" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const roles = await workos.authorization.listRoles();
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.list_environment_roles
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.list_environment_roles()
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().ListEnvironmentRoles(context.Background())
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->authorization()->listEnvironmentRoles();
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.authorization.listEnvironmentRoles();
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.ListEnvironmentRolesAsync();
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .list_environment_roles()
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "slug": "admin",
      "object": "role",
      "id": "role_01EHQMYV6MBK39QC5PZXHY59C3",
      "name": "Admin",
      "description": "Can manage all resources",
      "type": "EnvironmentRole",
      "resource_type_slug": "organization",
      "permissions": [
        "posts:read",
        "posts:write"
      ],
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

:::

## Set permissions for an environment role

Replace all permissions assigned to an environment role. This operation removes any existing permissions and assigns the provided permissions.

To remove all permissions from a role, pass an empty array.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PUT \
  --url "https://api.workos.com/authorization/roles/admin/permissions" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "permissions": [
            "billing:read",
            "billing:write",
            "invoices:manage",
            "reports:view"
        ]
    }
BODY
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const role = await workos.authorization.setRolePermissions('editor', {
  permissions: ['documents:read', 'documents:write', 'documents:publish'],
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.set_environment_role_permissions(
  slug: "admin",
  permissions: ["billing:read", "billing:write", "invoices:manage", "reports:view"]
)
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.set_environment_role_permissions(
    slug="admin",
    permissions=["billing:read", "billing:write", "invoices:manage", "reports:view"],
)
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().SetEnvironmentRolePermissions(context.Background(), "admin", &workos.AuthorizationSetEnvironmentRolePermissionsParams{
		Permissions: []any{"billing:read", "billing:write", "invoices:manage", "reports:view"},
	})
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->authorization()
    ->setEnvironmentRolePermissions(
        slug: "admin",
        permissions: [
            "billing:read",
            "billing:write",
            "invoices:manage",
            "reports:view",
        ],
    );
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;
import com.workos.authorization.AuthorizationApi.SetEnvironmentRolePermissionsOptions;

WorkOS workos = new WorkOS("sk_example_123456789");

SetEnvironmentRolePermissionsOptions options =
    SetEnvironmentRolePermissionsOptions.builder()
        .permissions(
            List.of("billing:read", "billing:write", "invoices:manage", "reports:view"))
        .build();

workos.authorization.setEnvironmentRolePermissions("admin", options);
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.SetEnvironmentRolePermissionsAsync(
    "admin", new AuthorizationSetEnvironmentRolePermissionsOptions {
        Permissions = new[] { "billing:read", "billing:write", "invoices:manage", "reports:view" },
    });
```

```rust language="rust" title="Request" tab="1"
use workos::Client;
use workos::authorization::SetEnvironmentRolePermissionsParams;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .set_environment_role_permissions(
            "admin",
            SetEnvironmentRolePermissionsParams {
                permissions: vec![
                    "billing:read".into(),
                    "billing:write".into(),
                    "invoices:manage".into(),
                    "reports:view".into(),
                ],
                ..Default::default()
            }
        )
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "slug": "admin",
  "object": "role",
  "id": "role_01EHQMYV6MBK39QC5PZXHY59C3",
  "name": "Admin",
  "description": "Can manage all resources",
  "type": "EnvironmentRole",
  "resource_type_slug": "organization",
  "permissions": [
    "billing:read",
    "billing:write",
    "invoices:manage",
    "reports:view"
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## Update an environment role

Update an existing environment role.

:::code-group

```bash language="curl" title="Request" tab="1"
curl --request PATCH \
  --url "https://api.workos.com/authorization/roles/admin" \
  --header "Authorization: Bearer sk_example_123456789" \
  --header "Content-Type: application/json" \
  -d @- <<'BODY'
    {
        "name": "Super Administrator",
        "description": "Full administrative access to all resources"
    }
BODY
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const role = await workos.authorization.updateRole('admin', {
  name: 'Super Administrator',
  description: 'Full administrative access to all resources',
});
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.authorization.update_environment_role(slug: "admin")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.authorization.update_environment_role(slug="admin")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.Authorization().UpdateEnvironmentRole(context.Background(), "admin")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->authorization()->updateEnvironmentRole(slug: "admin");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.authorization.updateEnvironmentRole("admin");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.Authorization.UpdateEnvironmentRoleAsync("admin");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .authorization()
        .update_environment_role("admin")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "slug": "admin",
  "object": "role",
  "id": "role_01EHQMYV6MBK39QC5PZXHY59C3",
  "name": "Super Administrator",
  "description": "Full administrative access to all resources",
  "type": "EnvironmentRole",
  "resource_type_slug": "organization",
  "permissions": [
    "posts:read",
    "posts:write"
  ],
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

### Role

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "role" | Yes | Distinguishes the Role object. |
| `id` | string | Yes | Unique identifier of the Role. |
| `name` | string | Yes | A descriptive name for the Role. This field does not need to be unique. |
| `slug` | string | Yes | A unique key to reference the role. Must be lowercase and contain only letters, numbers, hyphens, and underscores. |
| `description` | string \| null | Yes | A description for the Role. |
| `permissions` | string[] | Yes | A list of permission slugs assigned to the role. |
| `type` | "EnvironmentRole" | Yes | The type of Role. For environment roles, this is always `EnvironmentRole`. |
| `resource_type_slug` | string | Yes | The slug of the resource type the role is scoped to. |
| `created_at` | string | Yes | The timestamp when the Role was created. |
| `updated_at` | string | Yes | The timestamp when the Role was last updated. |

### POST /authorization/roles/{slug}/permissions

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The slug of the permission to add to the role. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `role` | object | Distinguishes the role object. |

### POST /authorization/roles

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | A unique key to reference the role. Must be lowercase and contain only letters, numbers, hyphens, and underscores. |
| `name` | string | Yes | A name for the role. |
| `description` | string | No | An optional description for the role. |
| `resource_type_slug` | string | No | The slug of the [resource type](/fga/resource-types) to scope the role to. Only applicable when using [Fine-Grained Authorization](/fga). Defaults to the organization resource type if not provided. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `role` | object | Distinguishes the role object. |

### GET /authorization/roles/{slug}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The unique slug of the role to retrieve. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `role` | object | Distinguishes the role object. |

### GET /authorization/roles

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `list` | object |  |

### PUT /authorization/roles/{slug}/permissions

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `permissions` | string[] | Yes | An array of permission slugs to assign to the role. This replaces all existing permissions. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The slug of the environment role. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `role` | object | Distinguishes the role object. |

### PATCH /authorization/roles/{slug}

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | The new name for the role. |
| `description` | string | No | The new description for the role. Set to `null` to remove the description. |

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `slug` | string | Yes | The slug of the environment role. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `role` | object | Distinguishes the role object. |