> ## Documentation Index > Fetch the complete documentation index at: https://docs.plerion.com/llms.txt > Use this file to discover all available pages before exploring further. # Set a user's navigation > Replaces the user's sidebar arrangement in the tenant. `order` is the whole arrangement, hidden entries included, and `hidden` names the entries in `order` that are tucked away. `home` is always first and never hidden; the server moves or shows it if a request says otherwise. Keys must come from the sidebar catalog, and an unknown key answers 400 with the allowed keys in the message. Requires an organization API key with read and write access. ## OpenAPI ````yaml /api-reference/organization-openapi.yaml put /v1/organization/users/{userId}/preferences/navigation openapi: 3.1.0 info: title: Plerion organization API version: v1 termsOfService: https://www.plerion.com/terms-and-conditions contact: name: Plerion Pty Ltd url: https://www.plerion.com/contact-us email: support@plerion.com license: name: Plerion Use License url: https://www.plerion.com/terms-and-conditions description: |- The Plerion organization API manages roles, role assignments and preferences for a whole organization: the roles that exist, the permissions each one grants, which users and user groups hold them, and the home dashboard and navigation each user or user group gets in a tenant. It covers the same lifecycle as the roles, user access and dashboard assignment pages of the Plerion app, so an automation can grant access and set defaults without a person signing in. Requests are authenticated with a Plerion organization API key sent as a bearer token. The organization is resolved from the key, so no request names an organization. List responses are `{ "data": [...], "meta": { "cursor": ... } }`. Pass `meta.cursor` back as the `cursor` query parameter to fetch the next page; it is `null` on the last page. Single objects are `{ "data": ... }`. Deletes answer 204 with no body. Errors are `{ "errors": [{ "code": ..., "message": ... }] }`. servers: - url: https://{region}.api.plerion.com description: Production API server - Select your preferred region variables: region: default: au enum: - au - sg1 - in1 - us1 security: - organizationApiKey: [] tags: - name: Roles x-displayName: Roles description: >- Built-in and custom roles. A built-in role's permissions are fixed and shown for reference; a custom role's permissions name actions or action groups from the permission catalog, optionally narrowed to specific integrations. - name: Role assignments x-displayName: Role assignments description: >- Which users and user groups hold which roles. A tenant-scoped role applies to one tenant; an organization-scoped role applies everywhere. - name: Permission catalog x-displayName: Permission catalog description: >- The actions and action groups a role's permissions may name, with the level and resource type of each action. Read this before writing a role. - name: Preferences x-displayName: Preferences description: >- The home dashboard and sidebar navigation a user or a user group gets in one tenant. A user's own setting wins, then the most recently updated of their user groups, then the tenant default (home dashboard only). Each setting is a sub-resource: PUT replaces it, DELETE clears it so the next level applies. paths: /v1/organization/users/{userId}/preferences/navigation: parameters: - $ref: '#/components/parameters/userId' put: tags: - Preferences summary: Set a user's navigation description: > Replaces the user's sidebar arrangement in the tenant. `order` is the whole arrangement, hidden entries included, and `hidden` names the entries in `order` that are tucked away. `home` is always first and never hidden; the server moves or shows it if a request says otherwise. Keys must come from the sidebar catalog, and an unknown key answers 400 with the allowed keys in the message. Requires an organization API key with read and write access. operationId: setUserNavigation parameters: - $ref: '#/components/parameters/tenantId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetNavigationRequest' example: order: - home - findings - risks - assets - alerts - threat-map hidden: - threat-map responses: '200': description: The stored preference, after normalisation. content: application/json: schema: $ref: '#/components/schemas/NavigationPreferenceResponse' '400': $ref: '#/components/responses/PreferenceBadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' x-codeSamples: - lang: bash label: curl source: |- curl --request PUT \ --url "https://au.api.plerion.com/v1/organization/users/7a3f9d8e-1b2c-4d5e-8f90-123456789abc/preferences/navigation?tenantId=65a72929-0e61-4c9c-b7a8-8abe6886fd6c" \ --header "Authorization: Bearer $PLERION_ORGANIZATION_API_KEY" \ --header "Content-Type: application/json" \ --data '{"order": ["home", "findings", "risks", "assets", "alerts", "threat-map"], "hidden": ["threat-map"]}' components: parameters: userId: name: userId in: path required: true description: The user id. schema: type: string format: uuid tenantId: name: tenantId in: query required: true description: >- The tenant the preference applies in. A PUT checks it belongs to the key's organization and answers 400 `TenantNotFound` otherwise; a GET or DELETE for a tenant outside the organization finds no row and answers 404 `PreferenceNotFound`. example: 65a72929-0e61-4c9c-b7a8-8abe6886fd6c schema: type: string format: uuid schemas: SetNavigationRequest: type: object required: - order - hidden additionalProperties: false properties: order: type: array uniqueItems: true description: >- The sidebar arrangement. Entries not listed are appended by the Plerion app in catalog order. example: - home - findings - risks - assets - alerts - threat-map items: type: string enum: - home - alerts - risks - findings - assets - agent-security - dspm - cwpp - compliance - ciem - threat-map - code-security - settings - well-architected - pinned-custom-reports hidden: type: array uniqueItems: true description: Entries from `order` to tuck away. Must be a subset of `order`. example: - threat-map items: type: string enum: - home - alerts - risks - findings - assets - agent-security - dspm - cwpp - compliance - ciem - threat-map - code-security - settings - well-architected - pinned-custom-reports NavigationPreferenceResponse: type: object properties: data: $ref: '#/components/schemas/NavigationPreference' NavigationPreference: type: object properties: tenantId: type: string format: uuid example: 65a72929-0e61-4c9c-b7a8-8abe6886fd6c order: type: array description: >- The whole sidebar arrangement, hidden entries included. `home` is always first. example: - home - findings - risks - assets - alerts - threat-map items: type: string enum: - home - alerts - risks - findings - assets - agent-security - dspm - cwpp - compliance - ciem - threat-map - code-security - settings - well-architected - pinned-custom-reports hidden: type: array description: >- The entries in `order` that are tucked away under the overflow menu. Never contains `home`. example: - threat-map items: type: string enum: - home - alerts - risks - findings - assets - agent-security - dspm - cwpp - compliance - ciem - threat-map - code-security - settings - well-architected - pinned-custom-reports updatedAt: type: string format: date-time example: '2026-10-05T04:12:00.000Z' Error: type: object properties: errors: type: array items: type: object properties: code: type: string message: type: string field: type: string description: Present on validation errors. required: - code - message required: - errors responses: PreferenceBadRequest: description: > `tenantId` is missing or not a uuid (`BadRequest`), the body is invalid (`InvalidBody`, with the allowed navigation keys in the message for an unknown key), a `hidden` entry is not in `order` (`BadRequest`), `tenantId` is not a tenant of the key's organization on a PUT (`TenantNotFound`), or the dashboard does not exist in that tenant (`ReportNotFound`). content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: ReportNotFound message: >- Custom report 3f1c7d2e-5a6b-4c8d-9e0f-1a2b3c4d5e6f was not found in tenant 65a72929-0e61-4c9c-b7a8-8abe6886fd6c Unauthorized: description: The organization API key is missing, malformed or revoked. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The key has the read access level and the operation writes, or the key is a tenant API key. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: > No such role, user, tenant, assignment or principal kind. Codes include `RoleNotFound`, `UserNotFound`, `TenantNotFound`, `AssignmentNotFound` and `PrincipalKindNotFound`. content: application/json: schema: $ref: '#/components/schemas/Error' example: errors: - code: RoleNotFound message: role not found securitySchemes: organizationApiKey: type: http scheme: bearer description: > Plerion organization API key (plerion_oak_…), created by an organization admin in the Plerion app. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.