---
title: "Read Role"
method: GET
path: "/api/configs/role/{name}"
tags: ["Config API"]
---

# Read Role

`GET /api/configs/role/{name}`

## Request

- The document declares no server URL.
- Auth: none declared

Read Role

## Path parameters

- `name` string, required

## Response `200`

Successful Response

- RoleOutput: ConfigMap-owned role definition used by read and validation APIs.
  - `name` string, required
  - `description` string, required
  - `policies` RolePolicy[], required
    - `effect` 'Allow' | 'Deny': Effect of a policy statement: Allow or Deny. Deny takes precedence over Allow.
    - `actions` string[], required
    - `resources` string[]
  - `immutable` boolean
  - `sync_mode` 'force' | 'import' | 'ignore': Sync mode for role assignments. - FORCE: Add from matching IDP claims and remove the IDP-derived assignment on the next human request without a matching claim. - IMPORT: Add from matching IDP claims and retain the assignment (default). - IGNORE: Never synchronize this role from IDP claims; manage it manually.
  - `external_roles` string[], nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-08-03** `b9d312a13f5d`: 2 info
  - added the optional property `detail/items/ctx` to the response with the `422` status
  - added the optional property `detail/items/input` to the response with the `422` status
- **2026-04-08** `a8157dc3279d`: 3 breaking, 5 warning, 2 info
  - response property `external_roles` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
  - the `policies/items/effect` response's property type changed from no type to `string` for status `200`
  - the `sync_mode` response's property type changed from no type to `string` for status `200`
  - added the new `Allow` enum value to the `policies/items/effect` response property for the response status `200`
  - …6 more
- **2026-03-31** `639e39b0d1eb`: 1 breaking, 6 info
  - the response's body type changed from `string` to `object` for status `200`
  - added the optional property `external_roles` to the response with the `200` status
  - added the optional property `immutable` to the response with the `200` status
  - added the optional property `sync_mode` to the response with the `200` status
  - …3 more

[Operation history](https://skmtc.dev/nvidia/apis/nvidia-corporation-osmo-api/changes/api/configs/role/:name/get.md)

---

[API](https://skmtc.dev/nvidia/apis/nvidia-corporation-osmo-api.md) - [All operations](https://skmtc.dev/nvidia/apis/nvidia-corporation-osmo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nvidia/apis/nvidia-corporation-osmo-api/revisions/845585a71dbb?raw)