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):

  1. Go to Dashboard > Applications and create a new application of type Machine to Machine.
  2. Go to the Dashboard > APIs and select the auth0-authorization-extension-api.
  3. Go to the Machine to Machine Applications tab, find the application you created at the first step, and toggle the Unauthorized to Authorized.
  4. 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}'

RESPONSE SAMPLE:

{
   "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
}

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}

RESPONSE SAMPLE:

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

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
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"}'

RESPONSE SAMPLE:

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

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}'
curl --request POST \
  --url 'https://{extension_url}/groups/{group_id}' \
  --header 'Authorization: Bearer {access_token}' \

RESPONSE SAMPLE:

(empty response body)

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"
}
curl --request PUT \
  --url 'https://{extension_url}/groups/{group_id}' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{ "name": "New name", "description": "New description" }'

RESPONSE SAMPLE:

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

RESPONSE SAMPLE:

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

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"
}
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"}]'

RESPONSE SAMPLE:

(empty response body)
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"
  ],
}
curl --request DELETE \
  --url 'https://{extension_url}/groups/{group_id}/mappings' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{"_id": ["7b57312c-579a-4798-bd91-9647563e1b8a"]}'

RESPONSE SAMPLE:

(empty response body)

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

RESPONSE SAMPLE:

{
   "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
      }
   ]
}

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" ]
curl --request PATCH \
  --url 'https://{extension_url}/groups/{group_id}/members' \
  --header 'Authorization: Bearer {access_token}' \
  --data '[ "{user_id}" ]'

RESPONSE SAMPLE:

(empty response body)

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

RESPONSE SAMPLE:

(empty response body)

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

RESPONSE SAMPLE:

{
   "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"
         }
      }
   ]
}

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

RESPONSE SAMPLE:

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

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}" ]
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}" ]'

RESPONSE SAMPLE:

(empty response body)

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}"]
curl --request DELETE \
  --url 'https://{extension_url}/groups/{group_id}/nested' \
  --header 'Authorization: Bearer {access_token}' \
  --data '["{NESTED_GROUP_ID}"]'

RESPONSE SAMPLE:

(empty response body)

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

RESPONSE SAMPLE:

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

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

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" ]
curl --request PATCH \
  --url 'https://{extension_url}/groups/{group_id}/roles' \
  --header 'Authorization: Bearer {access_token}' \
  --data '[ "{role_id}" ]'

RESPONSE SAMPLE:

(empty response body)

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}"]
curl --request DELETE \
  --url 'https://{extension_url}/groups/{group_id}/roles' \
  --header 'Authorization: Bearer {access_token}' \
  --data '["{role_id}"]'

RESPONSE SAMPLE:

(empty response body)

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

RESPONSE SAMPLE:

[
   {
      "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"
         ]
      }
   }
]

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

RESPONSE SAMPLE:

{
   "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
}

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}

RESPONSE SAMPLE:

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

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
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}"] }'

RESPONSE SAMPLE:

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

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}"
   ]
}
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}"] }'

RESPONSE SAMPLE:

{
   "_id":"22787849-f39c-4165-814f-6996ad8e72a0",
   "name":"My new example name",
   "description":"Example description",
   "applicationType":"client",
   "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa",
   "permissions":[
      "deeb552d-2d98-4efb-bb84-0c8babe5f431"
   ]
}
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}'
curl --request DELETE \
  --url 'https://{extension_url}/roles/{role_id}' \
  --header 'Authorization: Bearer {access_token}'

RESPONSE SAMPLE:

(empty response body)

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

RESPONSE SAMPLE:

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

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}

RESPONSE SAMPLE:

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

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
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" }'

RESPONSE SAMPLE:

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

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"
}
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" }'

RESPONSE SAMPLE:

{
   "_id":"bc6945e0-393a-4405-99d9-96903eaec4a1",
   "name":"New example name",
   "description":"Example description",
   "applicationType":"client",
   "applicationId":"LcGQZRtjVPPtZfq33I8vtKxldPKPRwBa"
}
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}'
curl --request DELETE \
  --url 'https://{extension_url}/permissions/{permission_id}' \
  --header 'Authorization: Bearer {access_token}'

RESPONSE SAMPLE:

(empty response body)

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

RESPONSE SAMPLE:

{
   "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
}

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}

RESPONSE SAMPLE:

{
   "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
}

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

RESPONSE SAMPLE:

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

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

RESPONSE SAMPLE:

(empty response body)

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

RESPONSE SAMPLE:

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

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

RESPONSE SAMPLE:

[
   {
      "_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"
   }
]

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

RESPONSE SAMPLE:

(empty response body)

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

RESPONSE SAMPLE:

(empty response body)

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

RESPONSE SAMPLE:

[
   {
      "_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"
   }
]

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
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}] }'

RESPONSE SAMPLE:

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

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

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)