Create custom scope

POST

/scopes

Last modified:2026-10-07 23:37:02

OperationId:createCustomScope

Creates a custom scope and returns it. Requires Super User scope. Super User Read Only can read scopes but cannot change them, and neither can a custom scope, even one derived from Super User.

A custom scope takes a built-in parent scope and removes rights from it, so it can never do more than its parent. Users and API keys are assigned it by name. Its rights come from these settings:

modifications. Per-object limits, keyed by API object name: none removes the object, ro allows reads only, update-only allows reads and updates, and no-delete allows everything but deletes.

read-only. yes refuses every write, on every object.

enabled. no refuses every token issued under the scope until you set it back to yes.

Changes apply to tokens already issued within seconds. Tokens are not reissued.

Send name and parent-scope. parent-scope is one of the eight built-in scopes you can derive from. A name already in use is a 409, and so is the name of a built-in scope. The scope is applied shortly after the response, so wait for it to appear before you assign it.

Request

Authorization

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

Responses

🟢200OK

application/json

The scope as created.

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠409Conflict

Request Example

Shell

JavaScript

Java

Swift

cURL

Limited Super UserRead-only Office Manager

curl --location 'https://awqacore01.crexendocloud.com/ns-api/v2/scopes' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "name": "Platform Manager",
    "parent-scope": "Super User",
    "description": "Operations admin with no platform configuration or routing changes",
    "modifications": {
        "nsconfig": "none",
        "route": "ro"
    }
}'

Response Example

200 - Limited Super User

{
    "name": "Platform Manager",
    "parent-scope": "Super User",
    "description": "Operations admin with no platform configuration or routing changes",
    "read-only": "no",
    "modifications": {
        "nsconfig": "none",
        "route": "ro"
    },
    "enabled": "yes",
    "hidden": "no",
    "built-in": "no"
}

Modified at 2026-10-07 23:37:02

List custom scopes

Count custom scopes