Create a Privilege
Use this API to create a new privilege object.
A privilege defines a set of actions that can be performed on particular resources in OneLogin.
A privilege doesn’t grant user access to perform actions. It describes what actions can be performed on a resource. In order to grant access, assign the privilege to a user or a role.
Preview Release
This API is part of the OneLogin Delegated Administration Service and only available as a preview release. If you’re interested in using this API, please contact your account manager or our support team.
Resource URL
POST https://api.<us_or_eu>.onelogin.com/api/1/privilegesHeader Parameters
Authorization required string | Set to Set Generate the access token with the API credential pair created using the scope required to call this API. Call this API using the |
Content-Type required string |
Set to application/json. |
Request Parameters
|
name required string |
The name of this privilege |
|
description string |
The description for this privilege |
|
privilege required object |
An object containing statements that describe the level of access granted by this privilege.
|
Statement
|
Effect required string |
Set to “Allow.” By default, all actions are denied, this Statement allows the listed actions to be executed. |
|
Action required array |
An array of strings that represent actions within OneLogin. Actions are prefixed with the class of object they are related to and followed by a specific action for the given class. e.g. users:List, where the class is users and the specific action is List. Don’t mix classes within an Action array. To create a privilege that includes multiple different classes, create multiple statements. A wildcard * that includes all actions is supported. Use wildcards to create a Super User privilege. Valid actions include the following: Apps
|
|
Scope required array |
Target the privileged action against specific resources with the scope. The scope pattern is the class of object used by the Action, followed by an ID that represents a resource in OneLogin. e.g. apps/1234, where apps is the class and 1234 is the ID of an app. The wildcard * is supported and indicates that all resources of the class type declared, in the Action, are in scope. The Action and Scope classes must match. However, there is an exception, a scope of roles/{role_id} can be combined with Actions on the user or app class. The exception allows you to target groups of users or apps with specific actions. |
Sample Request Body
Allow any action on any resource in OneLogin.
{
"name": "Super Administrator",
"description": "Can administer users",
"privilege": {
"Version": "2018-05-18",
"Statement": [{
"Effect": "Allow",
"Action": ["*"],
"Scope": ["*"]
}]
}
}Allow the following user actions on any user in OneLogin.
{
"name": "User Helpdesk",
"description": "Can administer helpdesk users",
"privilege": {
"Version": "2018-05-18",
"Statement": [{
"Effect": "Allow",
"Action": [
"users:List",
"users:Get",
"users:Unlock",
"users:ResetPassword",
"users:ForceLogout",
"users:GenerateTempMfaToken"
],
"Scope": ["*"]
}]
}
}Allow read only access to users or apps.
{
"name": "User or App Read Only",
"description": "Can administer users",
"privilege": {
"Version": "2018-05-18",
"Statement": [{
"Effect": "Allow",
"Action": [
"users:List",
"users:Get",
],
"Scope": ["*"]
},{
"Effect": "Allow",
"Action": [
"apps:List",
"apps:Get",
],
"Scope": ["*"]
}]
}
}Sample Response
- 200 OK
- 400 Bad Request
- 401 Unauthorized
{
"id": "5e43a548-e9c6-47be-9341-92160902f7a6"
}No statement or statement is missing an Actions array.
{
"statusCode": 400,
"name": "BadRequestError",
"message": "The request could not be understood by the server due to malformed syntax: Statement required Action array"
}Effect is missing in the statement
{
"statusCode": 400,
"name": "BadRequestError",
"message": "The request could not be understood by the server due to malformed syntax: Effect is required and must be 'Allow'"
}Invalid action was supplied. e.g. users:MadeUpAction
{
"statusCode": 400,
"name": "BadRequestError",
"message": "The request could not be understood by the server due to malformed syntax: Operation 'MadeUpAction' does not exist"
}This error indicates an invalid access token.
{
"statusCode": 401,
"name": "UnauthorizedError",
"message": "The request requires user authentication."
}Sample Code
cURL
curl 'https://api.<us_or_eu>.onelogin.com/api/1/privileges' \
-X POST \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
"name": "Super Administrator",
"description": "Can do super things",
"privilege": {
"Version": "2018-05-18",
"Statement": [{
"Effect": "Allow",
"Action": ["*"],
"Scope": ["*"]
}]
}
}'Postman Collection
Replace sample variables indicated by {{ }} with your actual values.
Download for the Privileges API
Have a Question?
Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.
Found a bug? Submit a support ticket.
Have a product idea or request? Share it with us in our Ideas Portal.