We use cookies to give you the best possible experience while you browse through our site. By continuing to use our website you implicitly agree to the usage of cookies on this site.

Read More
← Atlas API & Provisioning Reference

Roles

Schema

A role controls the access to resources and their actions within the API.

Type Object

Name Type Description
default_scope Enum(IGNORE, ACCOUNT, USER, SYSTEM):String Desc. default_scope
id String(format:uuid) Desc. id
inserted_at String(format:date-time) An ISO8601 formatted timestamp
level Enum(GUEST, CLIENT, ADMIN):String Desc. level
name String Desc. name
notes String Desc. notes
rank Integer(>= 0) Desc. rank
resources Array:SubObject Desc. resources
updated_at String(format:date-time) An ISO8601 formatted timestamp

Desc. default_scope

Role's default_scope, this is the scope applied when resources specify IGNORE for their own scope.

  • IGNORE - When used as the default_scope, effectively disables all resources that use IGNORE as their scope.
  • USER - Resources are scoped to the user, or their nearest account where applicable.
  • ACCOUNT - Resources are scoped against the user's account.
  • SYSTEM - Cannot be set by the API, but provided for reference, this is the system-wide scope.

Desc. id

A Universally unique identifier, which identifies the resource

Desc. level

The role's level dictates the overall access the associated user will have.

  • GUEST - Unprivileged user
  • CLIENT - This is the default level for Roles created from the API.
  • ADMIN - System administrators, cannot be set via the API, provided for reference.

Desc. name

Role's display name.

Desc. notes

Any notes about the role.

Desc. rank

Levels dictate the access, scopes filter resources, and ranks allow differentiating the same level of access within the account.

Ranks allow organizing roles within the account by importance.

0 is most relevant sometimes referred to as the highest rank. 1+ are ranks lower.

Ranks primarily affect the modification of: * Users - See Roles for information, as a user's Role dictates their permissions. * Roles - Roles of the same rank can modify themselves and those of lower rank, ranks of a higher rank cannot be modified by those of a lower rank.

SubObject

Sub-Schema

Type Object

Name Type Description
actions Array:SubObject
resource_id String
scope Enum(IGNORE, ACCOUNT, USER, SYSTEM):String Desc. scope

SubObject

Sub-Schema

Type Object

Name Type Description
name Enum:String Desc. name
value Enum(true, false):String Desc. value

Enum Values name

Allowed values

  • sell_rates
  • buy_rates
  • count
  • full_index
  • index
  • assoc
  • show
  • charge
  • reset
  • create
  • update
  • delete
  • purge
  • move
  • import
  • export
  • review
  • protect
  • share
  • unshare
  • impersonate
  • checkout
  • lookup_result
  • process
  • cancel
  • download
  • upload
  • summarize

Desc. name

The name of the action.

Desc. value

Whether or not the action is enabled.

NOTE. This is not a Boolean.

The field is an enum that happens to use the values true and false as strings.

Desc. scope

See Role's default_scope for more details on the enum.

IGNORE acts as a fallback to the default_scope.

Desc. resources

Role's job title, or position

Example

{
  "default_scope": "ACCOUNT",
  "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
  "inserted_at": "2021-08-13T04:08:44.762841Z",
  "level": "CLIENT",
  "name": "Ordering Role",
  "notes": "This role governs the Ordering System Access",
  "rank": 0,
  "resources": [
    {
      "actions": [
        {
          "name": "sell_rates",
          "value": "true"
        }
      ],
      "resource_id": "string",
      "scope": "IGNORE"
    }
  ],
  "updated_at": "2021-08-13T04:08:44.762841Z"
}

Summary

Roles control the permissions a user can have.

API

Create Role

Data

Name Type Description
default_scope Enum(IGNORE, ACCOUNT, USER, SYSTEM):String Desc. default_scope
name String Desc. name
notes String Desc. notes
rank Integer(>= 0) Desc. rank
resources Array:SubObject Desc. resources

Desc. default_scope

Role's default_scope, this is the scope applied when resources specify IGNORE for their own scope.

  • IGNORE - When used as the default_scope, effectively disables all resources that use IGNORE as their scope.
  • USER - Resources are scoped to the user, or their nearest account where applicable.
  • ACCOUNT - Resources are scoped against the user's account.
  • SYSTEM - Cannot be set by the API, but provided for reference, this is the system-wide scope.

Desc. name

Role's display name.

Desc. notes

Any notes about the role.

Desc. rank

Levels dictate the access, scopes filter resources, and ranks allow differentiating the same level of access within the account.

Ranks allow organizing roles within the account by importance.

0 is most relevant sometimes referred to as the highest rank. 1+ are ranks lower.

Ranks primarily affect the modification of: * Users - See Roles for information, as a user's Role dictates their permissions. * Roles - Roles of the same rank can modify themselves and those of lower rank, ranks of a higher rank cannot be modified by those of a lower rank.

SubObject

Sub-Schema

Type Object

Name Type Description
actions Array:SubObject
resource_id String
scope Enum(IGNORE, ACCOUNT, USER, SYSTEM):String Desc. scope

SubObject

Sub-Schema

Type Object

Name Type Description
name Enum:String Desc. name
value Enum(true, false):String Desc. value

Enum Values name

Allowed values

  • sell_rates
  • buy_rates
  • count
  • full_index
  • index
  • assoc
  • show
  • charge
  • reset
  • create
  • update
  • delete
  • purge
  • move
  • import
  • export
  • review
  • protect
  • share
  • unshare
  • impersonate
  • checkout
  • lookup_result
  • process
  • cancel
  • download
  • upload
  • summarize

Desc. name

The name of the action.

Desc. value

Whether or not the action is enabled.

NOTE. This is not a Boolean.

The field is an enum that happens to use the values true and false as strings.

Desc. scope

See Role's default_scope for more details on the enum.

IGNORE acts as a fallback to the default_scope.

Desc. resources

Role's job title, or position

POST /api/v1/roles HTTP/1.1

Create a new Role.

Note that newly created Roles will return their secrets, however all subsequent GET requests will not contain the secrets.

Request application/json

POST /api/v1/roles HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 392

{
  "data": {
    "default_scope": "ACCOUNT",
    "name": "Ordering Role",
    "notes": "This role governs the Ordering System Access",
    "rank": 0,
    "resources": [
      {
        "actions": [
          {
            "name": "sell_rates",
            "value": "true"
          }
        ],
        "resource_id": "string",
        "scope": "IGNORE"
      }
    ]
  },
  "type": "role"
}

Response 201

application/json
HTTP/1.1 201
Content-Type: application/json
Content-Length: 564

{
  "data": {
    "default_scope": "ACCOUNT",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "level": "CLIENT",
    "name": "Ordering Role",
    "notes": "This role governs the Ordering System Access",
    "rank": 0,
    "resources": [
      {
        "actions": [
          {
            "name": "sell_rates",
            "value": "true"
          }
        ],
        "resource_id": "string",
        "scope": "IGNORE"
      }
    ],
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "role"
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Update Role

Data

Name Type Description
default_scope Enum(IGNORE, ACCOUNT, USER, SYSTEM):String Desc. default_scope
name String Desc. name
notes String Desc. notes
rank Integer(>= 0) Desc. rank
resources Array:SubObject Desc. resources

Desc. default_scope

Role's default_scope, this is the scope applied when resources specify IGNORE for their own scope.

  • IGNORE - When used as the default_scope, effectively disables all resources that use IGNORE as their scope.
  • USER - Resources are scoped to the user, or their nearest account where applicable.
  • ACCOUNT - Resources are scoped against the user's account.
  • SYSTEM - Cannot be set by the API, but provided for reference, this is the system-wide scope.

Desc. name

Role's display name.

Desc. notes

Any notes about the role.

Desc. rank

Levels dictate the access, scopes filter resources, and ranks allow differentiating the same level of access within the account.

Ranks allow organizing roles within the account by importance.

0 is most relevant sometimes referred to as the highest rank. 1+ are ranks lower.

Ranks primarily affect the modification of: * Users - See Roles for information, as a user's Role dictates their permissions. * Roles - Roles of the same rank can modify themselves and those of lower rank, ranks of a higher rank cannot be modified by those of a lower rank.

SubObject

Sub-Schema

Type Object

Name Type Description
actions Array:SubObject
resource_id String
scope Enum(IGNORE, ACCOUNT, USER, SYSTEM):String Desc. scope

SubObject

Sub-Schema

Type Object

Name Type Description
name Enum:String Desc. name
value Enum(true, false):String Desc. value

Enum Values name

Allowed values

  • sell_rates
  • buy_rates
  • count
  • full_index
  • index
  • assoc
  • show
  • charge
  • reset
  • create
  • update
  • delete
  • purge
  • move
  • import
  • export
  • review
  • protect
  • share
  • unshare
  • impersonate
  • checkout
  • lookup_result
  • process
  • cancel
  • download
  • upload
  • summarize

Desc. name

The name of the action.

Desc. value

Whether or not the action is enabled.

NOTE. This is not a Boolean.

The field is an enum that happens to use the values true and false as strings.

Desc. scope

See Role's default_scope for more details on the enum.

IGNORE acts as a fallback to the default_scope.

Desc. resources

Role's job title, or position

PATCH /api/v1/roles/{id} HTTP/1.1

Update an existing Role

Path Parameters

Name Type Description
id String(format:uuid)! Role ID

Request application/json

PATCH /api/v1/roles/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 392

{
  "data": {
    "default_scope": "ACCOUNT",
    "name": "Ordering Role",
    "notes": "This role governs the Ordering System Access",
    "rank": 0,
    "resources": [
      {
        "actions": [
          {
            "name": "sell_rates",
            "value": "true"
          }
        ],
        "resource_id": "string",
        "scope": "IGNORE"
      }
    ]
  },
  "type": "role"
}

Response 200

application/json
HTTP/1.1 200
Content-Type: application/json
Content-Length: 564

{
  "data": {
    "default_scope": "ACCOUNT",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "level": "CLIENT",
    "name": "Ordering Role",
    "notes": "This role governs the Ordering System Access",
    "rank": 0,
    "resources": [
      {
        "actions": [
          {
            "name": "sell_rates",
            "value": "true"
          }
        ],
        "resource_id": "string",
        "scope": "IGNORE"
      }
    ],
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "role"
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Delete Role

DELETE /api/v1/roles/{id} HTTP/1.1

Delete a Role.

Note that a Role cannot be deleted if it is still associated with any switches or numbers.

Path Parameters

Name Type Description
id String(format:uuid)! Role ID

Request

DELETE /api/v1/roles/{id} HTTP/1.1
Accept: application/json

Response 200

application/json
HTTP/1.1 200
Content-Type: application/json
Content-Length: 564

{
  "data": {
    "default_scope": "ACCOUNT",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "level": "CLIENT",
    "name": "Ordering Role",
    "notes": "This role governs the Ordering System Access",
    "rank": 0,
    "resources": [
      {
        "actions": [
          {
            "name": "sell_rates",
            "value": "true"
          }
        ],
        "resource_id": "string",
        "scope": "IGNORE"
      }
    ],
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "role"
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

List Roles

GET /api/v1/roles HTTP/1.1

Retrieve a list of all roles under the parent account

Query Parameters

Name Type Description
first Integer Query Desc. first
last Integer Query Desc. last
after String Query Desc. after
before String Query Desc. before

Query Desc. first

The number of items to return starting from the 'after' cursor

Query Desc. last

The number of items to return behind the 'before' cursor

Query Desc. after

The cursor representing the starting point of a 'first' based paging

Query Desc. before

The cursor representing the starting point of a 'last' based paging

Request

GET /api/v1/roles HTTP/1.1
Accept: application/json

Response 200

application/json
HTTP/1.1 200
Content-Type: application/json
Content-Length: 825

{
  "count": 1,
  "page_info": {
    "first": "string",
    "has_next_page": true,
    "has_previous_page": true,
    "last": "string"
  },
  "results": [
    {
      "data": {
        "default_scope": "ACCOUNT",
        "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
        "inserted_at": "2021-08-13T04:08:44.762841Z",
        "level": "CLIENT",
        "name": "Ordering Role",
        "notes": "This role governs the Ordering System Access",
        "rank": 0,
        "resources": [
          {
            "actions": [
              {
                "name": "sell_rates",
                "value": "true"
              }
            ],
            "resource_id": "string",
            "scope": "IGNORE"
          }
        ],
        "updated_at": "2021-08-13T04:08:44.762841Z"
      },
      "type": "role"
    }
  ]
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Get Role

GET /api/v1/roles/{id} HTTP/1.1

Lookup a request by ID

Path Parameters

Name Type Description
id String(format:uuid)! Role ID

Request

GET /api/v1/roles/{id} HTTP/1.1
Accept: application/json

Response 200

application/json
HTTP/1.1 200
Content-Type: application/json
Content-Length: 564

{
  "data": {
    "default_scope": "ACCOUNT",
    "id": "c6be45e4-b7dd-412c-96c4-777e83fb9c48",
    "inserted_at": "2021-08-13T04:08:44.762841Z",
    "level": "CLIENT",
    "name": "Ordering Role",
    "notes": "This role governs the Ordering System Access",
    "rank": 0,
    "resources": [
      {
        "actions": [
          {
            "name": "sell_rates",
            "value": "true"
          }
        ],
        "resource_id": "string",
        "scope": "IGNORE"
      }
    ],
    "updated_at": "2021-08-13T04:08:44.762841Z"
  },
  "type": "role"
}

Response 403

application/json
HTTP/1.1 403
Content-Type: application/json
Content-Length: 312

{
  "errors": [
    {
      "code": "access_denied.no_scope",
      "detail": "No scope available to user role",
      "params": {
        "action": "index",
        "level": "guest",
        "resource": "resource"
      },
      "sub_code": "none",
      "title": "Access Denied, no scope available"
    }
  ]
}

Response 404

application/json
HTTP/1.1 404
Content-Type: application/json
Content-Length: 314

{
  "errors": [
    {
      "code": "not_found",
      "detail": "The specified resource could not be found",
      "params": {
        "resource": {
          "id": "3fbb573a-6049-44a0-a12c-d3a1ffae0b69",
          "type": "user"
        }
      },
      "sub_code": "none",
      "title": "Not Found"
    }
  ]
}

Updated 2026-08-12 · Generated from the Atlas OpenAPI spec.