> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/api-reference/advanced/roles.md).

# 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.