# Scopes

## Retrieving all scopes

> Retrieves all scopes for the tenant. Results can be filtered and sorted using query parameters.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Scopes"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.scope_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"iam.access_read":"","iam.access_manage":"","iam.assignment_create_own":"","iam.assignment_manage":"","iam.assignment_delete_own":"","iam.permission_read":"","iam.permission_create":"","iam.permission_update":"","iam.permission_delete":"","iam.role_read":"","iam.role_create":"","iam.role_update":"","iam.role_delete":"","iam.group_read":"","iam.group_read_own":"","iam.user_read":"","iam.user_read_own":"","iam.user_create":"","iam.user_update":"","iam.user_delete":"","iam.scope_manage":"","iam.scope_read":"","iam.scope_read_own":"","iam.resource_read":"","iam.template_read":""}}}}},"parameters":{"tenant":{"name":"tenant","in":"path","required":true,"description":"Your Emporix tenant name.\n\n**Note**: The tenant name should always be written in lowercase.\n","schema":{"pattern":"^[a-z][a-z0-9]+$","minLength":3,"maxLength":16,"type":"string"}},"trait_paged_pageNumber":{"name":"pageNumber","in":"query","description":"Page number to be retrieved. The number of the first page is 1.\n","schema":{"default":1,"minimum":1,"type":"integer"}},"trait_paged_pageSize":{"name":"pageSize","in":"query","description":"Number of items to be retrieved per page.\n","schema":{"default":60,"minimum":1,"type":"integer"}},"trait_sort":{"name":"sort","in":"query","description":"List of properties used to sort the results, separated by colons. The order of properties indicates their priority in sorting.\n\nPossible values:\n* `{fieldName}`\n* `{fieldName}:asc`\n* `{fieldName}:desc`\n\n**Note:** If you want to sort the results by localized properties, the possible values are as follows:\n  * `{fieldName}.{language}`\n  * `{fieldName}.{language}:asc`\n  * `{fieldName}.{language}:desc`\n\nIf the sorting direction is not specified, the fields are sorted in ascending order.","schema":{"type":"string"}},"trait_q_query_param":{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Standard query parameter used to search for specific values.   \n* Searching for an item by string property: `q=id:31065d5b-b62e`, where `id` is the field name and `31065d5b-b62e` is its required value.   \n* Searching for an item by localized field property: `q=name.en:T-s` where `name` is the name of the field, `en` is a language code and `T-s` is a required value of this field.   This query works only for localized fields, which are stored in a Map format where `key` is a language code and `value` is translation to particular language.   + Searching for items by date property. All numer-based property queries are valid also for dates. In that case the date should be placed within double quotes: `q=metadata.createdAt:(>=\"2021-05-18T07:27:27.455Z\" AND <\"2021-05-20T07:27:27.455Z\")`   + Searching for items with non existing or empty property: `q=name.en:null` where `name.en` is a name of fields that has value `null`.   + Searching for items with existing property: `q=attributes:exists` where `attributes` is a name of field that has `non null` value.   + Searching for items by multiple specific values: `q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494)` where `id` is name of field and strings within a bracket are it''s required value.   + Searching for items by multiple fields: `q=id:5c3325baa9812100098ff48f name.en:T-s` where `id` and ''name.en'' are the names of fields. All documents that contain given values of these fields are returned. Multiple fields separated by space can be specified. Multiple values for each field can be also specified in a format presented above.   + Searching for items with string fields conforming to a regex: `q=name.en:~ABCD12` or `q=name.en:(~AB CD)` - in case of searching for strings with space, where `name` is the name of field and `ABCD12` or `AB CD` is it''s querying regex.'\n"},"X-Total-Count":{"name":"X-Total-Count","in":"header","required":false,"schema":{"type":"boolean","default":false},"description":"Flag indicating whether the total number of retrieved items should be returned.\n"}},"schemas":{"CustomScopeQueryDocument":{"type":"object","description":"Definition of a scope.","properties":{"id":{"type":"string","description":"Scope identifier."},"description":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized description as a map of language codes to text."},"domain":{"type":"string","description":"Domain identifier for the scope."},"predefined":{"type":"boolean","readOnly":true,"description":"Indicates whether this scope is predefined in the system or was created by a user."},"metadata":{"$ref":"#/components/schemas/CustomScopeMetadataQueryDocument"}}},"CustomScopeMetadataQueryDocument":{"required":["createdAt","version"],"type":"object","properties":{"version":{"type":"integer","description":"Scope document version.","format":"int32"},"createdAt":{"type":"string","description":"Timestamp indicating when the scope was created.","format":"date-time"},"modifiedAt":{"type":"string","description":"Timestamp indicating when the scope was last modified.","format":"date-time"}},"description":"Scope metadata."}},"responses":{"Bad_request_400":{"description":"Unsupported language provided.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Scope validation failed, details will be provided in response message","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"status":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/iam/{tenant}/scopes":{"get":{"tags":["Scopes"],"summary":"Retrieving all scopes","description":"Retrieves all scopes for the tenant. Results can be filtered and sorted using query parameters.\n","operationId":"GET-iam-list-tenant-scopes","parameters":[{"$ref":"#/components/parameters/tenant"},{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/trait_sort"},{"$ref":"#/components/parameters/trait_q_query_param"},{"$ref":"#/components/parameters/X-Total-Count"}],"responses":{"200":{"description":"The request was successful. A list of scopes is returned.","headers":{"X-Total-Count":{"description":"Total number of retrieved scopes.","schema":{"type":"integer","format":"int32"}}},"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/CustomScopeQueryDocument"}}}}},"400":{"$ref":"#/components/responses/Bad_request_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```

## Retrieving a scope

> Retrieves details of a specified scope.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Scopes"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.scope_read"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"iam.access_read":"","iam.access_manage":"","iam.assignment_create_own":"","iam.assignment_manage":"","iam.assignment_delete_own":"","iam.permission_read":"","iam.permission_create":"","iam.permission_update":"","iam.permission_delete":"","iam.role_read":"","iam.role_create":"","iam.role_update":"","iam.role_delete":"","iam.group_read":"","iam.group_read_own":"","iam.user_read":"","iam.user_read_own":"","iam.user_create":"","iam.user_update":"","iam.user_delete":"","iam.scope_manage":"","iam.scope_read":"","iam.scope_read_own":"","iam.resource_read":"","iam.template_read":""}}}}},"parameters":{"trait_acceptLanguage_header":{"name":"Accept-Language","in":"header","required":false,"schema":{"type":"string"},"description":"List of language codes acceptable for the response. You can specify factors that indicate which language should be retrieved if the one with a higher factor was not found in the localized fields. If the value is specified, then it must be present in the tenant configuration.\n* If the header is set to a particular language or a list of languages, all localized fields are retrieved as strings.\n* If the header is set to `*`, all localized fields are retrieved as maps of translations, where the keys are language codes and values are the fields in their respective languages.\n* If the header is empty, localized fields are retrieved in the default language defined in the Configuration Service.\n"}},"schemas":{"CustomScopeQueryDocument":{"type":"object","description":"Definition of a scope.","properties":{"id":{"type":"string","description":"Scope identifier."},"description":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized description as a map of language codes to text."},"domain":{"type":"string","description":"Domain identifier for the scope."},"predefined":{"type":"boolean","readOnly":true,"description":"Indicates whether this scope is predefined in the system or was created by a user."},"metadata":{"$ref":"#/components/schemas/CustomScopeMetadataQueryDocument"}}},"CustomScopeMetadataQueryDocument":{"required":["createdAt","version"],"type":"object","properties":{"version":{"type":"integer","description":"Scope document version.","format":"int32"},"createdAt":{"type":"string","description":"Timestamp indicating when the scope was created.","format":"date-time"},"modifiedAt":{"type":"string","description":"Timestamp indicating when the scope was last modified.","format":"date-time"}},"description":"Scope metadata."},"ErrorResponse":{"required":["code","message","status"],"type":"object","properties":{"resourceId":{"type":"string","nullable":true},"code":{"type":"integer","format":"int32"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}},"responses":{"Bad_request_400":{"description":"Unsupported language provided.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Scope validation failed, details will be provided in response message","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"status":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/iam/{tenant}/scopes/{scopeId}":{"get":{"tags":["Scopes"],"summary":"Retrieving a scope","description":"Retrieves details of a specified scope.\n","operationId":"GET-iam-retrieve-scope","parameters":[{"$ref":"#/components/parameters/trait_acceptLanguage_header"}],"responses":{"200":{"description":"The request was successful. Scope details are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomScopeQueryDocument"}}}},"400":{"$ref":"#/components/responses/Bad_request_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"description":"Given resources cannot be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Upserting a custom scope

> Creates a custom scope when it does not exist, or updates it when it already exists for the tenant.\
> If \`metadata.version\` is provided, optimistic locking is applied for updates.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Scopes"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.scope_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"iam.access_read":"","iam.access_manage":"","iam.assignment_create_own":"","iam.assignment_manage":"","iam.assignment_delete_own":"","iam.permission_read":"","iam.permission_create":"","iam.permission_update":"","iam.permission_delete":"","iam.role_read":"","iam.role_create":"","iam.role_update":"","iam.role_delete":"","iam.group_read":"","iam.group_read_own":"","iam.user_read":"","iam.user_read_own":"","iam.user_create":"","iam.user_update":"","iam.user_delete":"","iam.scope_manage":"","iam.scope_read":"","iam.scope_read_own":"","iam.resource_read":"","iam.template_read":""}}}}},"schemas":{"CustomScopeUpsertRequest":{"type":"object","description":"Payload for creating or updating a scope.","properties":{"description":{"type":"object","additionalProperties":{"type":"string"},"description":"Localized description as a map of language codes to text."},"domain":{"type":"string","description":"Domain identifier for the scope."},"metadata":{"type":"object","description":"Metadata for the scope. Only `version` is supported, for optimistic locking on updates.","properties":{"version":{"type":"integer","format":"int32","description":"Document version. When provided on update, must match the stored version."}},"additionalProperties":false}}},"CustomScopeIdResponse":{"type":"object","properties":{"id":{"type":"string"}}}},"responses":{"Bad_request_400":{"description":"Unsupported language provided.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"status":{"type":"string"},"message":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Scope validation failed, details will be provided in response message","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"status":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/iam/{tenant}/scopes/{scopeId}":{"put":{"tags":["Scopes"],"summary":"Upserting a custom scope","description":"Creates a custom scope when it does not exist, or updates it when it already exists for the tenant.\nIf `metadata.version` is provided, optimistic locking is applied for updates.\n","operationId":"PUT-iam-upsert-custom-scope","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomScopeUpsertRequest"}}}},"responses":{"201":{"description":"The request was successful. The scope has been created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CustomScopeIdResponse"}}}},"204":{"description":"The request was successful. The scope has been updated."},"400":{"$ref":"#/components/responses/Bad_request_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```

## Deleting a custom scope

> Deletes a custom scope for the tenant.\
> \
> \*\*Note\*\*: The scope is removed and cannot be used anymore, but it may still appear on custom credentials that were already created before the deletion.<br>

```json
{"openapi":"3.0.1","info":{"title":"IAM Service","version":"0.0.1"},"tags":[{"name":"Scopes"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["iam.scope_manage"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"iam.access_read":"","iam.access_manage":"","iam.assignment_create_own":"","iam.assignment_manage":"","iam.assignment_delete_own":"","iam.permission_read":"","iam.permission_create":"","iam.permission_update":"","iam.permission_delete":"","iam.role_read":"","iam.role_create":"","iam.role_update":"","iam.role_delete":"","iam.group_read":"","iam.group_read_own":"","iam.user_read":"","iam.user_read_own":"","iam.user_create":"","iam.user_update":"","iam.user_delete":"","iam.scope_manage":"","iam.scope_read":"","iam.scope_read_own":"","iam.resource_read":"","iam.template_read":""}}}}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. It usually means that tenant from the token does not match tenant from path.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Scope validation failed, details will be provided in response message","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"status":{"type":"string"},"details":{"type":"array","items":{"type":"string"}}}}}}}}},"paths":{"/iam/{tenant}/scopes/{scopeId}":{"delete":{"tags":["Scopes"],"summary":"Deleting a custom scope","description":"Deletes a custom scope for the tenant.\n\n**Note**: The scope is removed and cannot be used anymore, but it may still appear on custom credentials that were already created before the deletion.\n","operationId":"DELETE-iam-delete-custom-scope","responses":{"204":{"description":"The request was successful. The scope has been deleted."},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"}}}}}}
```


---

# 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://developer.emporix.io/api-references/api-guides/users-and-permissions/iam/api-reference/scopes.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.