Language:

Introduction

The Authorization Extension API enables you to:

automate provisioning for your users, roles, groups, and permissions
query the authorization context of your users in real time

In order to use it, you first have to enable API access from your Authorization Dashboard.

For more information on the Authorization Extension and how to configure it, refer to Auth0 Authorization Extension.

For each endpoint in this explorer, you will find sample snippets you can use, in three available formats:

HTTP request
Curl command
JavaScript: depending on the endpoint each snippet may use Node.js or simple JavaScript

Each request should be sent with a Content-Type of application/json.

Find your extension URL

All endpoints in this explorer start with https://{extension_url}. This is the URL of your Authorization Dashboard. It differs based on you tenant's region:

Region	Extension URL
US West	`https://{yourTenant}.us.webtask.io/adf6e2f2b84784b57522e3b19dfc9201/api`
Europe	`https://{yourTenant}.eu.webtask.io/adf6e2f2b84784b57522e3b19dfc9201/api`
Australia	`https://{yourTenant}.au.webtask.io/adf6e2f2b84784b57522e3b19dfc9201/api`

Get an Access Token

When you enabled API access for your tenant, an API was created at your dashboard, which you can use to access the Authorization Extension API.

To do so you will have to configure a machine to machine application which will have access to this API and which you will use to get an Access Token.

Follow these steps to set up your application (you will have to do this only once):

Go to Dashboard > Applications and create a new application of type Machine to Machine.
Go to the Dashboard > APIs and select the auth0-authorization-extension-api.
Go to the Machine to Machine Applications tab, find the application you created at the first step, and toggle the Unauthorized to Authorized.
Select the scopes that should be granted to your application, based on the endpoints you want to access. For example, read:users to get all users.

To get an Access Token, you need to POST to the /oauth/token endpoint. You can find detailed instructions here.

Use this Access Token to access the Authorization Extension API.

Groups

Groups are collections of users. The groups that you will create are dependent on the needs of your business process. For example, you might have a group for your users in Finance, a group for your users in IT, and so on.

For more information, refer to Auth0 Authorization Extension.

Get all Groups

Examples

GET https://{extension_url}/groups
Authorization:  'Bearer {access_token}'

Was this helpful?

{
   "groups":[
      {
         "_id":"2a1e2b9f-3435-4954-8c5d-56e8e9ce763f",
         "name":"Test",
         "description":"Test",
         "members":[
            "auth0|59396da1b3c34a15589c780d"
         ],
         "mappings":[

         ]
      },
      {
         "_id":"81097bea-f7a3-48b6-a3fc-e2c3eb6c1ace",
         "name":"Google",
         "description":"Google",
         "mappings":[
            {
               "_id":"529e053f-285b-4f7f-b73c-c8c37b0ae4f2",
               "groupName":"Google",
               "connectionName":"google-oauth2"
            }
         ],
         "members":[
            "auth0|59396da1b3c34a15589c780d",
            "google-oauth2|113108011846505476166"
         ],
         "nested":[
            "2a1e2b9f-3435-4954-8c5d-56e8e9ce763f"
         ],
         "roles":[
            "9b814aac-87ba-4d84-8de6-3bcd0afee761"
         ]
      }
   ],
   "total":2
}

Was this helpful?

GET /groups

Use this endpoint to retrieve all groups.

Scopes

The Access Token should have the following scopes:

read:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token

Get a single Group

Examples

GET https://{extension_url}/groups/{group_id}

Was this helpful?

{
  "_id": "2a1e2b9f-3435-4954-8c5d-56e8e9ce763f",
  "name": "Test",
  "description": "Test"
}

Was this helpful?

GET /groups/{group_id}

Use this endpoint to get a single group based on its unique identifier. Add "?expand" to also load all roles and permissions for this group.

Scopes

The Access Token should have the following scopes:

read:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group to retrieve.

Create Group

Examples

Was this helpful?

curl --request POST \
  --url 'https://{extension_url}/groups' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{"name": "My name", "description": "My description"}'

Was this helpful?

{
  "name":"My name",
  "description":"My description",
  "_id":"3ea7dc85-3e50-4ba8-ae5a-4956ed6b26d5"
}

Was this helpful?

POST /groups

Use this endpoint to create a group.

Scopes

The Access Token should have the following scopes:

create:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`name` Required	The name of the new group
`description`	A description of the new group

Delete Group

Examples

POST https://{extension_url}/groups/{group_id}
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'

Was this helpful?

curl --request POST \
  --url 'https://{extension_url}/groups/{group_id}' \
  --header 'Authorization: Bearer {access_token}' \

Was this helpful?

(empty response body)

Was this helpful?

DELETE /groups/{group_id}

Use this endpoint to delete a group.

Scopes

The Access Token should have the following scopes:

delete:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group to delete

Update Group

Examples

PUT https://{extension_url}/groups/{group_id}
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
{
  name: "New name",
  description: "New description"
}

Was this helpful?

curl --request PUT \
  --url 'https://{extension_url}/groups/{group_id}' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{ "name": "New name", "description": "New description" }'

Was this helpful?

{
  "_id": "2a1e2b9f-3435-4954-8c5d-56e8e9ce763f",
  "name": "New name",
  "description": "New description",
  "members": [
    "auth0|59396da1b3c34a15589c780d"
  ]
}

Was this helpful?

PUT /groups/{group_id}

Use this endpoint to update the name or the description of a group.

Scopes

The Access Token should have the following scopes:

update:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group to update
`name` Required	The updated group name
`description` Required	The updated group description

Get Group Mappings

Examples

GET https://{extension_url}/groups/{group_id}/mappings

Was this helpful?

{
  "_id":"529e053f-285b-4f7f-b73c-c8c37b0ae4f2",
  "groupName":"Google",
  "connectionName":"google-oauth2 (google-oauth2)"
}

Was this helpful?

GET /groups/{group_id}/mappings

Use this endpoint to retrieve the mappings of a group.

Scopes

The Access Token should have the following scopes:

read:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group whose mappings you want to retrieve

Create Group Mappings

Examples

PATCH https://{extension_url}/groups/{group_id}/mappings
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
{
  groupName: "Test",
  connectionName: "google-oauth2"
}

Was this helpful?

curl -v -X PATCH \
  --url 'https://{extension_url}/api/groups/{group_id}/mappings' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer {access_token}' \
  --data '[{"groupName": "Test", "connectionName": "google-oauth2"}]'

Was this helpful?

(empty response body)

Was this helpful?

PATCH /groups/{group_id}/mappings

Use this endpoint to create one or more mappings in a group.

Group Mappings allow you to dynamically "add" users to different Groups based on the users' Connections. Essentially, using the Connection and the Groups information provided by the Identity Provider, you can dynamically make the user a member of the group in which you've created the appropriate mapping. For more information, refer to Group Mappings.

Scopes

The Access Token should have the following scopes:

update:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group whose mappings you want to retrieve
`groupName` Required	Group to add the users to
`connectionName` Required	Connection for the mapping

Delete Group Mappings

Examples

DELETE https://{extension_url}/groups/{group_id}/mappings
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
{
  _id: [
    "7b57312c-579a-4798-bd91-9647563e1b8a"
  ],
}

Was this helpful?

curl --request DELETE \
  --url 'https://{extension_url}/groups/{group_id}/mappings' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{"_id": ["7b57312c-579a-4798-bd91-9647563e1b8a"]}'

Was this helpful?

(empty response body)

Was this helpful?

DELETE /groups/{group_id}/mappings

Use this endpoint to delete one or more group mappings from a group.

Scopes

The Access Token should have the following scopes:

update:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more information on how to implement this, refer to our machine-to-machine flow implementation guide
`{group_id}` Required	The id of the group whose mappings you want to delete

Get Group Members

Examples

GET https://{extension_url}/groups/{group_id}/members

Was this helpful?

{
   "total":1,
   "users":[
      {
         "email":"richard.dowinton@auth0.com",
         "email_verified":true,
         "user_id":"auth0|59396da1b3c34a15589c780d",
         "picture":"https://s.gravatar.com/avatar/3e8ce75cfe7c53f13715df274f63e129?s=480&r=pg&d=https%3A%2F%2Fcdn.auth0.com%2Favatars%2Fri.png",
         "nickname":"richard.dowinton",
         "identities":[
            {
               "user_id":"59396da1b3c34a15589c780d",
               "provider":"auth0",
               "connection":"Username-Password-Authentication",
               "isSocial":false
            }
         ],
         "updated_at":"2017-06-25T07:28:54.719Z",
         "created_at":"2017-06-08T15:30:41.237Z",
         "name":"richard.dowinton@auth0.com",
         "app_metadata":{
            "authorization":{
               "roles":[

               ],
               "permissions":[

               ]
            }
         },
         "last_ip":"83.208.22.80",
         "last_login":"2017-06-25T07:28:54.719Z",
         "logins_count":12
      }
   ]
}

Was this helpful?

GET /groups/{group_id}/members

Use this endpoint to get the members for a group.

Scopes

The Access Token should have the following scopes:

read:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group whose members you want to retrieve
`{page}`	The page number. One-based.
`{per_page}`	The amount of entries per page. Default: `25`. Max value: `25`.

Add Group Members

Examples

PATCH https://{extension_url}/groups/{group_id}/members
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
[ "google-oauth2|113108011846505476166" ]

Was this helpful?

curl --request PATCH \
  --url 'https://{extension_url}/groups/{group_id}/members' \
  --header 'Authorization: Bearer {access_token}' \
  --data '[ "{user_id}" ]'

Was this helpful?

(empty response body)

Was this helpful?

PATCH /groups/{group_id}/members

Use this endpoint to add one or more members in a group.

Scopes

The Access Token should have the following scopes:

update:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group to which you want to add members
`{user_id}`	Id of the user to add in a group

Delete Group Members

Examples

DELETE https://{extension_url}/groups/{group_id}/members
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
["7b57312c-579a-4798-bd91-9647563e1b8a"]

Was this helpful?

curl --request DELETE \
  --url 'https://{extension_url}/groups/{group_id}/members' \
  --header 'Authorization: Bearer {access_token}' \
  --data '["7b57312c-579a-4798-bd91-9647563e1b8a"]'

Was this helpful?

(empty response body)

Was this helpful?

DELETE /groups/{group_id}/members

Use this endpoint to remove one or more members from a group.

Scopes

The Access Token should have the following scopes:

update:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group from which you want to remove members

Get Nested Group Members

Examples

GET https://{extension_url}/groups/{group_id}/members/nested

Was this helpful?

{
   "total":1,
   "nested":[
      {
         "user":{
            "user_id":"auth0|59396da1b3c34a15589c780d",
            "name":"richard.dowinton@auth0.com",
            "nickname":"richard.dowinton",
            "email":"richard.dowinton@auth0.com"
         },
         "group":{
            "_id":"2a1e2b9f-3435-4954-8c5d-56e8e9ce763f",
            "name":"New name",
            "description":"New description"
         }
      }
   ]
}

Was this helpful?

GET /groups/{group_id}/members/nested

Use this endpoint to get the nested members for a group.

Scopes

The Access Token should have the following scopes:

read:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group from which the nested members will be retrieved
`{page}`	The page number. One-based.
`{per_page}`	The amount of entries per page. Default: `25`. Max value: `25`.

Get Nested Groups

Examples

GET https://{extension_url}/groups/{group_id}/nested

Was this helpful?

[
   {
      "_id":"2a1e2b9f-3435-4954-8c5d-56e8e9ce763f",
      "name":"Test",
      "description":"Test",
      "members":[
         "auth0|59396da1b3c34a15589c780d"
      ]
   }
]

Was this helpful?

GET /groups/{group_id}/nested

Use this endpoint to get the nested groups for a group.

Scopes

The Access Token should have the following scopes:

read:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group from which the nested members will be retrieved

Add Nested Groups

Examples

PATCH https://{extension_url}/groups/{group_id}/nested
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
[ "{group_id_to_add}" ]

Was this helpful?

curl --request PATCH \
  --url 'https://{extension_url}/groups/{group_id}/nested' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '[ "{group_id_to_add}" ]'

Was this helpful?

(empty response body)

Was this helpful?

PATCH /groups/{group_id}/nested

Use this endpoint to add nested groups.

Scopes

The Access Token should have the following scopes:

update:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group to which you want to add members
`{group_id_to_add}`	List of group IDs that you want to add in the group

Delete Nested Groups

Examples

DELETE https://{extension_url}/groups/{group_id}/nested
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
["{NESTED_GROUP_ID}"]

Was this helpful?

curl --request DELETE \
  --url 'https://{extension_url}/groups/{group_id}/nested' \
  --header 'Authorization: Bearer {access_token}' \
  --data '["{NESTED_GROUP_ID}"]'

Was this helpful?

(empty response body)

Was this helpful?

DELETE /groups/{group_id}/nested

Use this endpoint to remove one or more nested groups.

Scopes

The Access Token should have the following scopes:

update:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group from which you want to remove other group members
`{NESTED_GROUP_ID}` Required	The id of the group to remove

Get Group Roles

Examples

GET https://{extension_url}/groups/{group_id}/roles

Was this helpful?

[
   {
      "applicationType":"client",
      "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
      "description":"Test",
      "name":"Test",
      "permissions":[

      ],
      "_id":"9b814aac-87ba-4d84-8de6-3bcd0afee761"
   }
]

Was this helpful?

GET /groups/{group_id}/roles

Use this endpoint to get the roles for a group.

Scopes

The Access Token should have the following scopes:

read:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group from which the nested members will be retrieved

Add Group Roles

Examples

PATCH https://{extension_url}/groups/{group_id}/roles
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
[ "google-oauth2|113108011846505476166" ]

Was this helpful?

curl --request PATCH \
  --url 'https://{extension_url}/groups/{group_id}/roles' \
  --header 'Authorization: Bearer {access_token}' \
  --data '[ "{role_id}" ]'

Was this helpful?

(empty response body)

Was this helpful?

PATCH /groups/{group_id}/roles

Use this endpoint to add roles to a group.

Scopes

The Access Token should have the following scopes:

update:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group to which you want to add members
`{role_id}`	List of role IDs to add in the group

Delete Group Roles

Examples

DELETE https://{extension_url}/groups/{group_id}/roles
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
["{GROUP_ROLES_ID}"]

Was this helpful?

curl --request DELETE \
  --url 'https://{extension_url}/groups/{group_id}/roles' \
  --header 'Authorization: Bearer {access_token}' \
  --data '["{role_id}"]'

Was this helpful?

(empty response body)

Was this helpful?

DELETE /groups/{group_id}/roles

Use this endpoint to remove one or more groups roles.

Scopes

The Access Token should have the following scopes:

update:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group from which you want to remove members
`{role_id}` Required	The IDs of the roles to be removed from the group

Get Nested Group Roles

Examples

GET https://{extension_url}/groups/{group_id}/roles/nested

Was this helpful?

[
   {
      "role":{
         "_id":"9b814aac-87ba-4d84-8de6-3bcd0afee761",
         "applicationType":"client",
         "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
         "description":"Test",
         "name":"Test",
         "permissions":[

         ],
         "users":[
            "auth0|59396da1b3c34a15589c780d"
         ]
      },
      "group":{
         "_id":"81097bea-f7a3-48b6-a3fc-e2c3eb6c1ace",
         "name":"Google",
         "description":"Google",
         "mappings":[
            {
               "_id":"529e053f-285b-4f7f-b73c-c8c37b0ae4f2",
               "groupName":"Google",
               "connectionName":"google-oauth2"
            }
         ],
         "members":[
            "auth0|59396da1b3c34a15589c780d",
            "google-oauth2|113108011846505476166"
         ],
         "nested":[
            "2a1e2b9f-3435-4954-8c5d-56e8e9ce763f"
         ],
         "roles":[
            "9b814aac-87ba-4d84-8de6-3bcd0afee761"
         ]
      }
   }
]

Was this helpful?

GET /groups/{group_id}/roles/nested

Use this endpoint to get the nested roles for a group.

Scopes

The Access Token should have the following scopes:

read:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your application retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{group_id}` Required	The id of the group from which the nested members will be retrieved

Roles

Roles are collections of permissions. For example, let's say that you have an application that allows employees to enter in company expenses. You want all employees to be able to submit expenses, but want certain Finance users to have more admin type of actions such as being able to approve or delete expenses. These actions can be mapped to Permissions and then assigned to a certain role.

For more information, refer to Auth0 Authorization Extension.

Get all Roles

Examples

GET https://{extension_url}/roles

Was this helpful?

{
   "roles":[
      {
         "applicationType":"client",
         "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
         "description":"Test",
         "name":"Test",
         "permissions":[

         ],
         "_id":"9b814aac-87ba-4d84-8de6-3bcd0afee761"
      },
      {
         "applicationType":"client",
         "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
         "description":"Example",
         "name":"Example 2",
         "permissions":[

         ],
         "_id":"7f3d03a7-b44e-4605-ad68-c2d94912a692"
      }
   ],
   "total":2
}

Was this helpful?

GET /roles

Use this endpoint to retrieve all roles.

Scopes

The Access Token should have the following scopes:

read:roles

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token

Get a single Role

Examples

GET https://{extension_url}/roles/{role_id}

Was this helpful?

{
   "_id":"9b814aac-87ba-4d84-8de6-3bcd0afee761",
   "name":"Test",
   "description":"Test"
}

Was this helpful?

GET /roles/{role_id}

Use this endpoint to get a single role based on its unique identifier.

Scopes

The Access Token should have the following scopes:

read:roles

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{role_id}` Required	The id of the role to retrieve.

Create Role

Examples

Was this helpful?

curl --request POST \
  --url 'https://{extension_url}/roles' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{ "name":"My new example name", "description":"Example description", "applicationType":"client", "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa", "permissions":["{permission_id}"] }'

Was this helpful?

{
   "name":"Example name",
   "description":"Example description",
   "applicationType":"client",
   "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
   "permissions":[
      "bc6945e0-393a-4405-99d9-96903eaec4a1"
   ],
   "_id":"22787849-f39c-4165-814f-6996ad8e72a0"
}

Was this helpful?

POST /roles

Use this endpoint to create a role.

Scopes

The Access Token should have the following scopes:

create:roles

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`name`	The new role's name
`description`	The new role's description
`applicationType`	The new role's application type
`applicationId`	The new role's application Id
`permissions`	A comma separated list of permissions (`{permission_id}`) for the new role

Update Role

Examples

PUT https://{extension_url}/roles/{role_id}
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
{
   "name":"My new example name",
   "description":"Example description",
   "applicationType":"client",
   "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
   "permissions":[
      "{permission_id}"
   ]
}

Was this helpful?

curl --request PUT \
  --url 'https://{extension_url}/roles/{role_id}' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '{ "name":"My new example name", "description":"Example description", "applicationType":"client", "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa", "permissions":["{permission_id}"] }'

Was this helpful?

{
   "_id":"22787849-f39c-4165-814f-6996ad8e72a0",
   "name":"My new example name",
   "description":"Example description",
   "applicationType":"client",
   "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
   "permissions":[
      "deeb552d-2d98-4efb-bb84-0c8babe5f431"
   ]
}

Was this helpful?

PUT /roles/{role_id}

Use this endpoint to update the details of a role.

Scopes

The Access Token should have the following scopes:

update:roles

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{role_id}` Required	The id of the role to update
`name`	The updated role name
`description`	The updated role description
`applicationType`	The updated application type
`applicationId`	The updated application Id
`permissions`	The updated list of permissions

Delete Role

Examples

DELETE https://{extension_url}/roles/{role_id}
Authorization:  'Bearer {access_token}'

Was this helpful?

curl --request DELETE \
  --url 'https://{extension_url}/roles/{role_id}' \
  --header 'Authorization: Bearer {access_token}'

Was this helpful?

(empty response body)

Was this helpful?

DELETE /roles/{role_id}

Use this endpoint to remove a role.

Scopes

The Access Token should have the following scopes:

delete:roles

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{role_id}` Required	The id of the role to delete

Permissions

Permissions are actions or functions that a user, or group of user, is allowed to do. For example, let's say that you have an application that allows employees to enter in company expenses. You want all employees to be able to submit expenses, but want certain Finance users to have more admin type of actions such as being able to approve or delete expenses. These actions can be mapped to permissions (which later on can be grouped in roles):

For more information, refer to Auth0 Authorization Extension.

Get all Permissions

Examples

GET https://{extension_url}/permissions

Was this helpful?

{
   "permissions":[
      {
         "applicationType":"client",
         "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
         "description":"Example permission",
         "name":"Example",
         "_id":"deeb552d-2d98-4efb-bb84-0c8babe5f431"
      }
   ],
   "total":1
}

Was this helpful?

GET /permissions

Use this endpoint to retrieve all permissions.

Scopes

The Access Token should have the following scopes:

read:permissions

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token

Get a single Permission

Examples

GET https://{extension_url}/permissions/{permission_id}

Was this helpful?

{
   "_id":"deeb552d-2d98-4efb-bb84-0c8babe5f431",
   "name":"Example",
   "description":"Example permission"
}

Was this helpful?

GET /permissions/{permission_id}

Use this endpoint to get a single permission based on its unique identifier.

Scopes

The Access Token should have the following scopes:

read:permissions

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{permission_id}` Required	The id of the permission to retrieve.

Create Permission

Examples

Was this helpful?

curl --request POST \
  --url 'https://{extension_url}/permissions' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{ "name":"Example name", "description":"Example description", "applicationType":"client", "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa" }'

Was this helpful?

{
   "name":"Example name",
   "description":"Example description",
   "applicationType":"client",
   "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
   "_id":"4dcdbcbb-e598-4b8f-abc1-7feb57dc54fe"
}

Was this helpful?

POST /permissions

Use this endpoint to create a permission.

Scopes

The Access Token should have the following scopes:

create:permissions

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`name`	The new permission's name
`description`	The new permission's description
`applicationType`	The new permission's application type
`applicationId`	The new permission's application Id

Update Permission

Examples

PUT https://{extension_url}/permissions/{permission_id}
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
{
   "name":"New example name",
   "description":"Example description",
   "applicationType":"client",
   "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa"
}

Was this helpful?

curl --request PUT \
  --url 'https://{extension_url}/permissions/{permission_id}' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{ "name":"New example name", "description":"Example description", "applicationType":"client", "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa" }'

Was this helpful?

{
   "_id":"bc6945e0-393a-4405-99d9-96903eaec4a1",
   "name":"New example name",
   "description":"Example description",
   "applicationType":"client",
   "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa"
}

Was this helpful?

PUT /permissions/{permission_id}

Use this endpoint to update the details of a permission.

Scopes

The Access Token should have the following scopes:

update:permissions

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{permission_id}` Required	The id of the permission to update
`name`	The updated permission name
`description`	The updated permission description
`applicationType`	The updated application type
`applicationId`	The updated application Id

Delete Permission

Examples

DELETE https://{extension_url}/permissions/{permission_id}
Authorization:  'Bearer {access_token}'

Was this helpful?

curl --request DELETE \
  --url 'https://{extension_url}/permissions/{permission_id}' \
  --header 'Authorization: Bearer {access_token}'

Was this helpful?

(empty response body)

Was this helpful?

DELETE /permissions/{permission_id}

Use this endpoint to remove a permission.

Scopes

The Access Token should have the following scopes:

delete:permissions

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{permission_id}` Required	The id of the permission to delete

Users

These endpoints enable you to manage all the current users of your applications. You can retrieve their profile and edit or view their groups and their roles.

For more information, refer to Auth0 Authorization Extension.

Get all Users

Examples

GET https://{extension_url}/users

Was this helpful?

{
   "start":0,
   "limit":100,
   "length":5,
   "users":[
      {
         "logins_count":12,
         "identities":[
            {
               "isSocial":false,
               "user_id":"59091da1b3c34a15589c780d",
               "provider":"auth0",
               "connection":"Username-Password-Authentication"
            }
         ],
         "user_id":"auth0|59091da1b3c34a15589c780d",
         "last_login":"2017-06-25T07:28:54.719Z",
         "name":"placeholder.user@example.com",
         "picture":"https://s.gravatar.com/avatar/your-gravatar.png",
         "email":"richard.dowinton@auth0.com"
      }
   ],
   "total":1
}

Was this helpful?

GET /users

Use this endpoint to retrieve all users.

Scopes

The Access Token should have the following scopes:

read:users

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{page}`	The page number. One-based.
`{per_page}`	The amount of entries per page. Default: `100`. Max value: `200`.

Get a single User

Examples

GET https://{extension_url}/users/{user_id}

Was this helpful?

{
   "email":"placeholder.user@example.com",
   "email_verified":true,
   "user_id":"auth0|59091da1b3c34a15589c780d",
   "picture":"https://s.gravatar.com/avatar/your-gravatar.png",
   "nickname":"placeholder.user",
   "identities":[
      {
         "user_id":"59091da1b3c34a15589c780d",
         "provider":"auth0",
         "connection":"Username-Password-Authentication",
         "isSocial":false
      }
   ],
   "updated_at":"2017-06-25T07:28:54.719Z",
   "created_at":"2017-06-08T15:30:41.237Z",
   "name":"placeholder.user@example.com",
   "app_metadata":{
      "authorization":{
         "roles":[

         ],
         "permissions":[

         ]
      }
   },
   "last_ip":"83.208.22.80",
   "last_login":"2017-06-25T07:28:54.719Z",
   "logins_count":12
}

Was this helpful?

GET /users/{user_id}

Use this endpoint to get a single user based on its unique identifier.

Scopes

The Access Token should have the following scopes:

read:users

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{user_id}` Required	The id of the user to retrieve.

Get User Groups

Examples

GET https://{extension_url}/users/{user_id}/groups

Was this helpful?

[
   {
      "_id":"2a1e2b9f-3435-4954-8c5d-56e8e9ce763f",
      "name":"Test",
      "description":"Test"
   },
   {
      "_id":"81097bea-f7a3-48b6-a3fc-e2c3eb6c1ace",
      "name":"Google",
      "description":"Google"
   }
]

Was this helpful?

GET /users/{user_id}/groups

Use this endpoint to get the groups of a single user, based on its unique identifier. Add "?expand" to also load all roles and permissions for these groups.

Scopes

The Access Token should have the following scopes:

read:users

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{user_id}` Required	The id of the user to retrieve.

Add User to Groups

Examples

PATCH https://{extension_url}/users/{user_id}/groups
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
[ "{group_id}" ]

Was this helpful?

curl --request PATCH \
  --url 'https://{extension_url}/users/{user_id}/groups' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '[ "{group_id}" ]'

Was this helpful?

(empty response body)

Was this helpful?

PATCH /users/{user_id}/groups

Use this endpoint to add a user to one or more groups.

Scopes

The Access Token should have the following scopes:

update:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{user_id}` Required	The id of the user that you want to add to groups
`{group_id}` Required	The id of the group to which you want to add users

Calculate Group Memberships

Examples

GET https://{extension_url}/users/{user_id}/groups/calculate

Was this helpful?

[
   {
      "_id":"2a1e2b9f-3435-4954-8c5d-56e8e9ce763f",
      "name":"Test",
      "description":"Test"
   },
   {
      "_id":"81097bea-f7a3-48b6-a3fc-e2c3eb6c1ace",
      "name":"Google",
      "description":"Google"
   }
]

Was this helpful?

GET /users/{user_id}/groups/calculate

Use this endpoint to calculate the group memberships for a user (including nested groups).

Scopes

The Access Token should have the following scopes:

read:groups

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{user_id}` Required	The id of the user for whom you want to calculate the group memberships

Get User Roles

Examples

GET https://{extension_url}/users/{user_id}/roles

Was this helpful?

[
   {
      "_id":"9b814aac-87ba-4d84-8de6-3bcd0afee761",
      "name":"Test",
      "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
      "description":"Test"
   },
   {
      "_id":"7f3d03a7-b44e-4605-ad68-c2d94912a692",
      "name":"Example 2",
      "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
      "description":"Example"
   }
]

Was this helpful?

GET /users/{user_id}/roles

Use this endpoint to get the roles of a single user, based on its unique identifier.

Scopes

The Access Token should have the following scopes:

read:users

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{user_id}` Required	The id of the user for whom you want to retrieve the roles

Add User to Roles

Examples

PATCH https://{extension_url}/users/{user_id}/roles
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
[ "{role_id}" ]

Was this helpful?

curl --request PATCH \
  --url 'https://{extension_url}/users/{user_id}/roles' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '[ "{role_id}" ]'

Was this helpful?

(empty response body)

Was this helpful?

PATCH /users/{user_id}/roles

Use this endpoint to assign a role to a user.

Scopes

The Access Token should have the following scopes:

update:users

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{user_id}` Required	The id of the user that you want to assign to roles
`{role_id}` Required	The id of the role to which you want to assign users

Remove User from Roles

Examples

DELETE https://{extension_url}/users/{user_id}/roles
Content-Type:   'application/json'
Authorization:  'Bearer {access_token}'
[ "{role_id}" ]

Was this helpful?

curl --request DELETE \
  --url 'https://{extension_url}/users/{user_id}/roles' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'Content-Type: application/json' \
  --data '[ "{role_id}" ]'

Was this helpful?

(empty response body)

Was this helpful?

DELETE /users/{user_id}/roles

Use this endpoint to remove one or more user from a role.

Scopes

The Access Token should have the following scopes:

update:roles

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{user_id}` Required	The id of the user you want to remove from roles
`body` Required	The id of the role(s) you want to remove users from (i.e. `[ "{role_id}" ]`)

Calculate Roles

Examples

GET https://{extension_url}/users/{user_id}/roles/calculate

Was this helpful?

[
   {
      "_id":"9b814aac-87ba-4d84-8de6-3bcd0afee761",
      "name":"Test",
      "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
      "description":"Test"
   },
   {
      "_id":"7f3d03a7-b44e-4605-ad68-c2d94912a692",
      "name":"Example 2",
      "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
      "description":"Example"
   }
]

Was this helpful?

GET /users/{user_id}/roles/calculate

Use this endpoint to calculate the roles assigned to the user (including through group memberships).

Scopes

The Access Token should have the following scopes:

read:roles

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 in order to access the API. For more info, see Get an Access Token
`{user_id}` Required	The id of the user for whom you want to calculate the roles

Execute Authorization Policy

Examples

Was this helpful?

curl --request POST \
  --url 'https://{extension_url}/users/{user_id}/policy/{client_id}' \
  --header 'Authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{ "connectionName": "Username-Password-Database", "groups": [{group_id}] }'

Was this helpful?

{
   "groups":[
      "New name",
      "Google",
      "My name"
   ],
   "permissions":[

   ],
   "roles":[
      "Test",
      "Example 2"
   ]
}

Was this helpful?

POST /users/{user_id}/policy/{client_id}

Use this endpoint to execute the authorization policy for a user in the context of a client. This will return the user's groups but also roles and permissions that apply to the current client.

Scopes

The Access Token should have the following scopes:

read:users

Parameters

Parameter	Description
`{extension_url}` Required	The URL of your Authorization Extension. For more info, see Find your extension URL
`{access_token}` Required	The token your client retrieved from Auth0 to access the API. For more info, see Get an Access Token
`{user_id}` Required
`{client_id}` Required
`connectionName` Required	The name of the connection with which the user logged in
`groups`	List of group names received from the IdP (AD, ADFS, and so on)