# 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"}]}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thewalletcrew.io/develop/api-reference/advanced/roles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.