# Roles

## List available roles and permissions for the tenant

> Returns role definitions and associated permission.\
>             \
> \## Authorization\
> Requires \`tenant.access:read\` scope.

```json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Roles"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"RoleDefinition":{"required":["name","permissions"],"type":"object","properties":{"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}}},"paths":{"/api/{tenantId}/admin/roles":{"get":{"tags":["Roles"],"summary":"List available roles and permissions for the tenant","description":"Returns role definitions and associated permission.\n            \n## Authorization\nRequires `tenant.access:read` scope.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Roles returned.","content":{"text/plain":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RoleDefinition"}}},"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RoleDefinition"}}},"text/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/RoleDefinition"}}}}}}}}}}
```

## Create a new role

> Adds a new role entry to \`security.yml\`.\
>             \
> \## Authorization\
> Requires \`tenant.access.role:write\` scope.

```json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Roles"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"CreateRoleRequest":{"required":["name","permissions"],"type":"object","properties":{"name":{"minLength":1,"type":"string","description":"Role name. Only alphanumeric characters, hyphens, underscores and dots are allowed.\nCannot be \"administrator\"."},"permissions":{"type":"array","items":{"type":"string"},"description":"List of permission scopes granted to this role. Use [\"*\"] for full access."}},"additionalProperties":false,"description":"Request body to create a role."},"RoleDefinition":{"required":["name","permissions"],"type":"object","properties":{"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/admin/roles":{"post":{"tags":["Roles"],"summary":"Create a new role","description":"Adds a new role entry to `security.yml`.\n            \n## Authorization\nRequires `tenant.access.role:write` scope.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"Request body to create a role.","$ref":"#/components/schemas/CreateRoleRequest"}},"text/json":{"schema":{"description":"Request body to create a role.","$ref":"#/components/schemas/CreateRoleRequest"}},"application/*+json":{"schema":{"description":"Request body to create a role.","$ref":"#/components/schemas/CreateRoleRequest"}}},"required":true},"responses":{"201":{"description":"Role created.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/RoleDefinition"}},"application/json":{"schema":{"$ref":"#/components/schemas/RoleDefinition"}},"text/json":{"schema":{"$ref":"#/components/schemas/RoleDefinition"}}}},"400":{"description":"Name is invalid or permissions are missing.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"409":{"description":"A role with this name already exists, or the name is reserved.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}}
```

## Get a specific role and permissions for the tenant

> Returns role definition and associated permissions for a single role.\
>             \
> \## Authorization\
> Requires \`tenant.access:read\` scope, or the caller must have the same role as \`roleName\`.

```json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Roles"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"paths":{"/api/{tenantId}/admin/roles/{roleName}":{"get":{"tags":["Roles"],"summary":"Get a specific role and permissions for the tenant","description":"Returns role definition and associated permissions for a single role.\n            \n## Authorization\nRequires `tenant.access:read` scope, or the caller must have the same role as `roleName`.","parameters":[{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}},{"name":"roleName","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Role returned.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/RoleDefinition"}},"application/json":{"schema":{"$ref":"#/components/schemas/RoleDefinition"}},"text/json":{"schema":{"$ref":"#/components/schemas/RoleDefinition"}}}},"401":{"description":"Caller not authorized.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"404":{"description":"Role not found.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}},"components":{"schemas":{"RoleDefinition":{"required":["name","permissions"],"type":"object","properties":{"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}}}
```

## Update a role's permissions

> Replaces the permission list of an existing role in \`security.yml\`.\
> The "administrator" role cannot be modified.\
>             \
> \## Authorization\
> Requires \`tenant.access.role:write\` scope.

```json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Roles"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"UpdateRoleRequest":{"required":["permissions"],"type":"object","properties":{"permissions":{"type":"array","items":{"type":"string"},"description":"New list of permission scopes granted to this role. Use [\"*\"] for full access."}},"additionalProperties":false,"description":"Request body to update a role's permissions."},"RoleDefinition":{"required":["name","permissions"],"type":"object","properties":{"name":{"type":"string"},"permissions":{"type":"array","items":{"type":"string"}}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/admin/roles/{roleName}":{"put":{"tags":["Roles"],"summary":"Update a role's permissions","description":"Replaces the permission list of an existing role in `security.yml`.\nThe \"administrator\" role cannot be modified.\n            \n## Authorization\nRequires `tenant.access.role:write` scope.","parameters":[{"name":"roleName","in":"path","required":true,"schema":{"type":"string"}},{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"description":"Request body to update a role's permissions.","$ref":"#/components/schemas/UpdateRoleRequest"}},"text/json":{"schema":{"description":"Request body to update a role's permissions.","$ref":"#/components/schemas/UpdateRoleRequest"}},"application/*+json":{"schema":{"description":"Request body to update a role's permissions.","$ref":"#/components/schemas/UpdateRoleRequest"}}},"required":true},"responses":{"200":{"description":"Role updated.","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/RoleDefinition"}},"application/json":{"schema":{"$ref":"#/components/schemas/RoleDefinition"}},"text/json":{"schema":{"$ref":"#/components/schemas/RoleDefinition"}}}},"400":{"description":"Permissions are missing.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"404":{"description":"Role not found.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"409":{"description":"The role is the immutable \"administrator\" role.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}}
```

## Delete a role

> Removes a role from \`security.yml\`.\
> The "administrator" role cannot be deleted.\
>             \
> \## Authorization\
> Requires \`tenant.access.role:write\` scope.

```json
{"openapi":"3.1.1","info":{"title":"Neostore internal API","version":"v1"},"tags":[{"name":"Roles"}],"servers":[{"url":"https://app.neostore.cloud","description":"Production Server"},{"url":"https://app-qa.neostore.cloud","description":"Staging Server"}],"security":[{"admin-bearer":["ScopedAuthorizeRequirement"]},{"apiKey":["ScopedAuthorizeRequirement"]}],"components":{"securitySchemes":{"admin-bearer":{"type":"oauth2","flows":{"implicit":{"authorizationUrl":"https://auth.neostore.cloud/authorize?audience=https://app.neostore.cloud/api/","scopes":{}}}},"apiKey":{"type":"apiKey","name":"X-API-KEY","in":"header"}},"schemas":{"ProblemDetails":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"type":["null","integer"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]}},"additionalProperties":{}},"HttpValidationProblemDetails":{"type":"object","allOf":[{"$ref":"#/components/schemas/ProblemDetails"}],"properties":{"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}},"additionalProperties":{}}}},"paths":{"/api/{tenantId}/admin/roles/{roleName}":{"delete":{"tags":["Roles"],"summary":"Delete a role","description":"Removes a role from `security.yml`.\nThe \"administrator\" role cannot be deleted.\n            \n## Authorization\nRequires `tenant.access.role:write` scope.","parameters":[{"name":"roleName","in":"path","required":true,"schema":{"type":"string"}},{"name":"tenantId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"Role deleted."},"404":{"description":"Role not found.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}},"409":{"description":"The role is the immutable \"administrator\" role.","content":{"text/plain":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}},"text/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ProblemDetails"},{"$ref":"#/components/schemas/HttpValidationProblemDetails"}]}}}}}}}}}
```