Introduction

The Authorization Extension API enables you to:

automate provisioning for your users, scopesAccess TokenspasswordlessAccess Tokensscope(s)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.

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://YOUR_TENANT.us.webtask.io/adf6e2f2b84784b57522e3b19dfc9201/api`
Europe	`https://YOUR_TENANT.eu.webtask.io/adf6e2f2b84784b57522e3b19dfc9201/api`
Australia	`https://YOUR_TENANT.au.webtask.io/adf6e2f2b84784b57522e3b19dfc9201/api`

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 Allowed Callback URLsscopesRefresh TokensUniversal LoginAccess 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 audienceRefresh Tokenscopes 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.

Scope Descriptions

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

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

Use this endpoint to retrieve all groups.

The Single Sign-on (SSO)callbackAccess Token should have the following Refresh TokensSingle Sign-on (SSO)scopes:

read:groups

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 https://{extension_url}/groups/{group_id}

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

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

The Passwordless authenticationAccess Token should have the following noncescopes:

read:groups

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.

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

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

POST /groups

Use this endpoint to create a group.

The Access TokenAccess Token should have the following Single Sign-on (SSO)scopes:

create:groups

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

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

(empty response body)

Use this endpoint to delete a group.

Error Codes and Descriptions

The Access Token should have the following scopes:

delete:groups

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

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

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

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

The Access Token should have the following scopes:

update:groups

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 https://{extension_url}/groups/{group_id}/mappings

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

Use this endpoint to retrieve the mappings of a group.

The Access Token should have the following scopes:

read:groups

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

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

(empty response body)

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.

The Access Token should have the following scopes:

update:groups

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

(empty response body)

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

The Access Token should have the following scopes:

update:groups

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 https://{extension_url}/groups/{group_id}/members

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

Use this endpoint to get the members for a group.

The Access Token should have the following scopes:

read:groups

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`.

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

(empty response body)

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

The Access Token should have the following scopes:

update:groups

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

(empty response body)

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

The Access Token should have the following scopes:

update:groups

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 https://{extension_url}/groups/{group_id}/members/nested

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

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

The Access Token should have the following scopes:

read:groups

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 https://{extension_url}/groups/{group_id}/nested

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

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

The Access Token should have the following scopes:

read:groups

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

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

(empty response body)

Use this endpoint to add nested groups.

The Access Token should have the following scopes:

update:groups

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

(empty response body)

Use this endpoint to remove one or more nested groups.

The Access Token should have the following scopes:

update:groups

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 https://{extension_url}/groups/{group_id}/roles

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

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

Use this endpoint to get the roles for a group.

The Access Token should have the following scopes:

read:groups

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

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

(empty response body)

Use this endpoint to add roles to a group.

The Access Token should have the following scopes:

update:groups

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

(empty response body)

Use this endpoint to remove one or more groups roles.

The Access Token should have the following scopes:

update:groups

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 https://{extension_url}/groups/{group_id}/roles/nested

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

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

The Access Token should have the following scopes:

read:groups

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 https://{extension_url}/roles

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

Use this endpoint to retrieve all roles.

The Access Token should have the following scopes:

read:roles

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 https://{extension_url}/roles/{role_id}

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

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

The Access Token should have the following scopes:

read:roles

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.

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

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

The Access Token should have the following scopes:

create:roles

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

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

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

Use this endpoint to update the details of a role.

The Access Token should have the following scopes:

update:roles

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

(empty response body)

Use this endpoint to remove a role.

The Access Token should have the following scopes:

delete:roles

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 https://{extension_url}/permissions

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

Use this endpoint to retrieve all permissions.

The Access Token should have the following scopes:

read:permissions

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 https://{extension_url}/permissions/{permission_id}

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

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

The Access Token should have the following scopes:

read:permissions

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.

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

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

The Access Token should have the following scopes:

create:permissions

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

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

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

Use this endpoint to update the details of a permission.

The Access Token should have the following scopes:

update:permissions

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

(empty response body)

Use this endpoint to remove a permission.

The Access Token should have the following scopes:

delete:permissions

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 https://{extension_url}/users

{
   "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":"dummy.user@example.com",
         "picture":"https://s.gravatar.com/avatar/your-gravatar.png",
         "email":"richard.dowinton@auth0.com"
      }
   ],
   "total":1
}

Use this endpoint to retrieve all users.

The Access Token should have the following scopes:

read:users

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 https://{extension_url}/users/{user_id}

{
   "email":"dummy.user@example.com",
   "email_verified":true,
   "user_id":"auth0|59091da1b3c34a15589c780d",
   "picture":"https://s.gravatar.com/avatar/your-gravatar.png",
   "nickname":"dummy.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":"dummy.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
}

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

The Access Token should have the following scopes:

read:users

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 https://{extension_url}/users/{user_id}/groups

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

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.

The Access Token should have the following scopes:

read:users

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.

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

(empty response body)

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

The Access Token should have the following scopes:

update:groups

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

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

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

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

The Access Token should have the following scopes:

read:groups

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 https://{extension_url}/users/{user_id}/roles

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

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

The Access Token should have the following scopes:

read:users

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

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

(empty response body)

Use this endpoint to assign a role to a user.

The Access Token should have the following scopes:

update:users

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

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

(empty response body)

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

The Access Token should have the following scopes:

update:roles

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}" ]`)

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

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

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

The Access Token should have the following scopes:

read:roles

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

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

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

The Access Token should have the following scopes:

read:users

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
`{client_id}` Required
`connectionName`	The connection name the user logged in with
`groups`	List of group names received from the IdP (AD, ADFS, and so on)

Introduction

Tenant specific variables

Types of applications

OIDC-conformant pipeline and tokens

Advantages of linking accounts

Regular web apps

Ready-to-go example

Find your extension URL

Project Planning Guide

Creating a third-party application

Access vs. ID Tokens

The linking process

Native/mobile apps

Setup and initialization

Get an Access Token

Groups

Keep reading

Consent dialog

Scopes

Merging Metadata

Single-page apps

Configure your Auth0 application for embedded login

Get all Groups

Scope Descriptions

Further reading

Use the Management API

Don't store tokens in local storage

Installation options

Examples

Handling rejected permissions

Use Auth0.js

Using cookies

Initialization

GET /groups

Skipping consent for first-party applications

Scenarios

If a backend is present

Available parameters

Scopes

Revoking Consent

Automatic account linking

If no backend is present

Scope

Parameters

Password-based flows

User-initiated account linking

Login

Get a single Group

Forcing users to provide consent

Suggested account linking

webAuth.authorize()

Examples

Customizing the consent dialog

Unlinking accounts

webAuth.popup.authorize()

GET /groups/{group_id}

Properties from secondary identities

Handling popup authentication results

Scopes

webAuth.login()

Parameters

webAuth.crossOriginVerification()

Create Group

buildAuthorizeUrl(options)

Examples

Single Sign-On with embedded authentication

POST /groups

Passwordless login

Scopes

Start passwordless

Parameters

Verify passwordless

Delete Group

Extract the authResult and get user info

Examples

Using nonces

DELETE /groups/{group_id}

Error Codes and Descriptions

Scopes

Logout