Authority limit profiles

In ClaimCenter, an authority limit is a restriction placed upon a user that limits the types of transactions that user can make. It can also determine whether these new transactions require approval from someone with greater authority. An authority limit profile is a named collection of authority limits. Through Cloud API, you can create, modify, delete, and retrieve information about authority limit profiles.

Note that there are two types of authority limit profiles: assignable and custom. The information used by an authority profile limit changes based on its type.

  • An assignable authority limit profile is created outside of the context of any user and it can be assigned to multiple users. Assignable authority limit profiles capture logic that is needed by a large group of users.
  • A custom authority limit profile is created for a specific user. Custom authority limit profiles are a convenient way of specifying authority limits for a user whose needs are unlikely to be shared by any other user. Custom authority limit profiles cannot be shared across users.

Retrieving information about authority limit profiles

To retrieve information about an authority limit profile and its limits, use the following endpoints.

Endpoint Retrieves
GET /admin/v1/authority-limit-profiles A list of all authority limit profiles
GET /admin/v1/authority-limit-profiles/{authorityLimitProfileId} Information about a specific authority limit profile
GET /admin/v1/authority-limit-profiles/{authorityLimitProfileId}/limits A list of limits for a specific authority limit profile
GET /admin/v1/authority-limit-profiles/{authorityLimitProfileId}/limits/{limitId} Information about a specific limit in a specific authority limit profile

For example, the following request retrieves information about authority profile limit "default_data:1".

GET /admin/v1/authority-limit-profiles/default_data:1

{
    "data": {
        "attributes": {
            "currency": {
                "code": "usd",
                "name": "USD"
            },
            "custom": false,
            "description": "Adjuster default authority",
            "displayName": "Adjuster",
            "id": "default_data:1",
            "name": "Adjuster"
        }
     }
     ...
}

The following request retrieves information about the limits for authority profile limit "default_data:1". There are two limits, one limiting claim payments to date to $15,000 USD and one limiting claim total reserves to $15,000 USD.

GET /admin/v1/authority-limit-profiles/default_data:1/limits

{
    "count": 2,
    "data": [
        {
            "attributes": {
                "id": "default_data:2",
                "limitAmount": {
                    "amount": "15000.00",
                    "currency": "usd"
                },
                "limitType": {
                    "code": "cptd",
                    "name": "Claim payments to date"
                }
            },
            ...
        },
        {
            "attributes": {
                "id": "default_data:1",
                "limitAmount": {
                    "amount": "15000.00",
                    "currency": "usd"
                },
                "limitType": {
                    "code": "ctr",
                    "name": "Claim total reserves"
                }
            },
            ...
        }
    ]

Creating authority limit profiles

To create an assignable authority limit profile, use the following endpoint:

  • POST /admin/v1/authority-limit-profiles

Create an assignable profile

An assignable authority limit profile is created outside of the context of any user and it can be assigned to multiple users. Assignable authority limit profiles capture logic that is needed by a large group of users.

For assignable authority limit profiles, you must specify the following:

  • name
  • currency (a typecode from the Currency typelist)

The AuthorityLimitProfile resource also has a custom field, which defaults to false. Therefore, for assignable authority limit profiles, you do not need to specify it.

For example, the following creates a new assignable authority limit profile whose name is "financial admin" and whose currency is USD.

POST /admin/v1/authority-limit-profiles

{
  "data": {
    "attributes": {
        "name": "Financial admin",
        "currency": {
            "code": "usd"
        }
    }
  }
}

Create a custom profile

A custom authority limit profile is created for a specific user. Custom authority limit profiles are a convenient way of specifying authority limits for a user whose needs are unlikely to be shared by any other user. Custom authority limit profiles cannot be shared across users.

For custom authority limit profiles, you must specify the following:

  • custom (which must be set to true)
  • currency (a typecode from the Currency typelist)

You cannot specify a name for a custom authority limit profile.

For example, the following creates a new custom authority limit profile whose currency is USD.

POST /admin/v1/authority-limit-profiles

{
  "data": {
    "attributes": {
        "custom": true,
        "currency": {
            "code": "usd"
        }
    }
  }
}

Note that in the ClaimCenter user interface, you cannot create a custom profile that is not assigned to any user. Custom profiles are always created in the context of a specific user. In Cloud API, you can create a custom profile that is not assigned to any user. You can then assign that profile to a single user. However, if you attempt to assign it to multiple users, the second attempt will fail.

Assigning authority limit profiles to users

You can assign an authority profile limit to a user either when you POST the user or by PATCHing the user. To assign the profile, include the authorityLimitProfile attribute, and set the child id field to the id of the appropriate profile.

For example, the following request assigns authority limit profile cc:999 to user demo_sample:10.

PATCH /admin/v1/users/demo_sample:10

{
  "data": {
    "attributes": {
      "authorityLimitProfile": {
        "id": "cc:999"
      }
    }
  }
}

You can assign assignable profiles to any number of users. You can assign custom profiles to only a single user. If you attempt to assign a custom profile to multiple users, you will get a validation error similar to the following:

"The custom authority limit profile is associated with another user. Each custom authority 
limit profile can be associated to only a single user."

Adding limits to the profile

To add a limit to a profile, use the following endpoint:

  • POST /admin/v1/authority-limit-profiles/{authorityLimitProfileId}/limits

Each call to the /authority-limit-profiles/{authorityLimitProfileId}/limits endpoint can specify only one limit. To create multiple limits for a profile, you must invoke the endpoint multiple times.

You must specify two values for each limit:

  • The limitType, which is a code from the AuthorityLimitType typelist.
  • The limitAmount, which must specify an amount and a currency

For example, the following adds the claims total reserves limit (ctr) to authority limit profile cc:1208. The amount is 15,000 USD.

POST /admin/v1/authority-limit-profiles/cc:1208/limits

{
  "data": {
    "attributes": {
        "limitType": {
            "code": "ctr"
        },
        "limitAmount": {
            "currency": "usd",
            "amount": "15000"
        }
    }
  }
}

Creating authority limit profiles and grants in a single call

You can create an authority limit profile and one or more limits for the profile in a single call using request inclusion. In this case, the name of the included resource is AuthorityLimit. For more information on request inclusion, see Request inclusion.

For example, the following call creates an authority limit profile and two limits (claim total reserves limited to $15000 and payment amount limited to $5000).

POST /admin/v1/authority-limit-profiles

{
  "data": {
    "attributes": {
        "name": "Financial admin",
        "currency": {
            "code": "usd"
        }
    }
  },
  "included": {
    "AuthorityLimit": [
      {
        "attributes": {
            "limitType": {
                "code": "ctr"
            },
            "limitAmount": {
                "currency": "usd",
                "amount": "15000"
            }
        },
        "method": "post",
        "uri": "/admin/v1/authority-limit-profiles/this/limits"
      },
      {
        "attributes": {
            "limitType": {
                "code": "pa"
            },
            "limitAmount": {
                "currency": "usd",
                "amount": "5000"
            }
        },
        "method": "post",
        "uri": "/admin/v1/authority-limit-profiles/this/limits"
      }      
    ]
  }  
}

Updating authority limit profiles

Use the following endpoints to modify an existing authority limit profile.

Endpoint Description
PATCH /admin/v1/authority-limit-profiles/{authorityLimitProfileId} Modify attributes about the given authority limit profile
PATCH /admin/v1/authority-limit-profiles/{authorityLimitProfileId}/limits/{limitId} Modify attributes about the given limit for the given authority limit profile
DELETE /authority-limit-profiles/{authorityLimitProfileId}/limits/{limitId} Remove the given limit from the given authority limit profile
DELETE /admin/v1/authority-limit-profiles/{authorityLimitProfileId} Delete the given authority limit profile

Examples of PATCHing an authority limit profile

The following request modifies the name and description of authority limit profile cc:1208.

PATCH /admin/v1/authority-limit-profile/cc:1208

{
  "data": {
    "attributes": {
      "name": "Finance Administrator",
      "description": "Authority limit profile for finance administrators"
    }
  }
}

The following request modifies the cc:33 limit (claim total reserve) of authority limit profile cc:1208.

PATCH /admin/v1/authority-limit-profile/cc:1208/limits/cc:33

{
  "data": {
    "attributes": {
        "limitAmount": {
            "currency": "usd",
            "amount": "30000"
        }
    }
  }
}

Example of removing a limit

The following request removes limit id cc:33 (claim total reserve) from authority limit profile cc:1208.

DELETE /admin/v1/authority-limit-profile/cc:1208/limits/cc:33

<no request body>

Example of DELETEing an authority limit profile

The following request deletes authority limit profile cc:1208.

DELETE /admin/v1/authority-limit-profile/cc:1208

<no request body>

You cannot a delete an authority limit profile if it is associated with one or more users.