Define Organization Behavior

When representing your application in Auth0, you can specify what types of users the application should support. Some applications support individuals logging in with personal accounts, while others are intended for use by members of organizations. Some should support both. This is known as organization behavior and can be set for each application that you connect to Auth0.

For example, your application could have:

  • a generic marketing landing page that has a Log in button that takes your users to the Auth0 login flow without an Organization

  • a separate URL for each of your B2B customers (e.g., Acme users go to acme.yourcompany.com) that redirects users to Auth0 with an Organization, so that your users see Acme’s SSO Login button

You can define Organization behavior to allow either of these scenarios. Additionally, you can configure Organization behavior such that if your application requires that an Organization be provided but your user accidentally is sent to Auth0 without an organization, they would see a prompt that would allow them to enter the name of their organization.

You can define organization behavior using either the Auth0 Dashboard or the Management API.

Auth0 Dashboard

To define organization behavior via the Auth0 Dashboard:

  1. Navigate to Auth0 Dashboard > Applications, and select the application for which you want to configure organizations.

  2. Select the Organizations view, and configure the appropriate settings:

    Field Description
    What types of end-users will access this application? Allows you to control the type of users that will log in to your application. Options include:
    • Individuals for personal use: Users cannot log in using an organization.
    • Team members of organizations: Users must log in using an organization. When selected, you must either provide an organization when you redirect users to the /authorize endpoint or choose Pre-login prompt as your Organization Prompt Type to allow users to choose an organization before they log in.
    • Both: Users can log in either with an organization or without one.
    Display Organization Prompt Specifies whether to prompt users to enter an organization name before logging in. If disabled, you must send the Organization ID to Auth0 to display the proper organization login prompt.

  3. Select Save changes.

Management API

Make a PATCH call to the Update a Client endpoint. Be sure to replace CLIENT_ID, MGMT_API_ACCESS_TOKEN, ORG_USAGE, and ORG_REQUIRE_BEHAVIOR placeholder values with your client ID, Management API Access Token, organization use option, and organization behavior option, respectively.


curl --request PATCH \
  --url 'https://YOUR_DOMAIN/api/v2/clients/CLIENT_ID' \
  --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/json' \
  --data '{ "organization_usage": "ORG_USAGE", "organization_require_behavior": "ORG_REQUIRE_BEHAVIOR" }'
var client = new RestClient("https://YOUR_DOMAIN/api/v2/clients/CLIENT_ID");
var request = new RestRequest(Method.PATCH);
request.AddHeader("content-type", "application/json");
request.AddHeader("authorization", "Bearer MGMT_API_ACCESS_TOKEN");
request.AddHeader("cache-control", "no-cache");
request.AddParameter("application/json", "{ \"organization_usage\": \"ORG_USAGE\", \"organization_require_behavior\": \"ORG_REQUIRE_BEHAVIOR\" }", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io/ioutil"
)

func main() {

	url := "https://YOUR_DOMAIN/api/v2/clients/CLIENT_ID"

	payload := strings.NewReader("{ \"organization_usage\": \"ORG_USAGE\", \"organization_require_behavior\": \"ORG_REQUIRE_BEHAVIOR\" }")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("content-type", "application/json")
	req.Header.Add("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
	req.Header.Add("cache-control", "no-cache")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := ioutil.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.patch("https://YOUR_DOMAIN/api/v2/clients/CLIENT_ID")
  .header("content-type", "application/json")
  .header("authorization", "Bearer MGMT_API_ACCESS_TOKEN")
  .header("cache-control", "no-cache")
  .body("{ \"organization_usage\": \"ORG_USAGE\", \"organization_require_behavior\": \"ORG_REQUIRE_BEHAVIOR\" }")
  .asString();
var axios = require("axios").default;

var options = {
  method: 'PATCH',
  url: 'https://YOUR_DOMAIN/api/v2/clients/CLIENT_ID',
  headers: {
    'content-type': 'application/json',
    authorization: 'Bearer MGMT_API_ACCESS_TOKEN',
    'cache-control': 'no-cache'
  },
  data: {
    organization_usage: 'ORG_USAGE',
    organization_require_behavior: 'ORG_REQUIRE_BEHAVIOR'
  }
};

axios.request(options).then(function (response) {
  console.log(response.data);
}).catch(function (error) {
  console.error(error);
});
#import <Foundation/Foundation.h>

NSDictionary *headers = @{ @"content-type": @"application/json",
                           @"authorization": @"Bearer MGMT_API_ACCESS_TOKEN",
                           @"cache-control": @"no-cache" };
NSDictionary *parameters = @{ @"organization_usage": @"ORG_USAGE",
                              @"organization_require_behavior": @"ORG_REQUIRE_BEHAVIOR" };

NSData *postData = [NSJSONSerialization dataWithJSONObject:parameters options:0 error:nil];

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://YOUR_DOMAIN/api/v2/clients/CLIENT_ID"]
                                                       cachePolicy:NSURLRequestUseProtocolCachePolicy
                                                   timeoutInterval:10.0];
[request setHTTPMethod:@"PATCH"];
[request setAllHTTPHeaderFields:headers];
[request setHTTPBody:postData];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
                                            completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
                                                if (error) {
                                                    NSLog(@"%@", error);
                                                } else {
                                                    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
                                                    NSLog(@"%@", httpResponse);
                                                }
                                            }];
[dataTask resume];
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://YOUR_DOMAIN/api/v2/clients/CLIENT_ID",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => "{ \"organization_usage\": \"ORG_USAGE\", \"organization_require_behavior\": \"ORG_REQUIRE_BEHAVIOR\" }",
  CURLOPT_HTTPHEADER => [
    "authorization: Bearer MGMT_API_ACCESS_TOKEN",
    "cache-control: no-cache",
    "content-type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
import http.client

conn = http.client.HTTPSConnection("")

payload = "{ \"organization_usage\": \"ORG_USAGE\", \"organization_require_behavior\": \"ORG_REQUIRE_BEHAVIOR\" }"

headers = {
    'content-type': "application/json",
    'authorization': "Bearer MGMT_API_ACCESS_TOKEN",
    'cache-control': "no-cache"
    }

conn.request("PATCH", "/YOUR_DOMAIN/api/v2/clients/CLIENT_ID", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))
require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://YOUR_DOMAIN/api/v2/clients/CLIENT_ID")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Patch.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Bearer MGMT_API_ACCESS_TOKEN'
request["cache-control"] = 'no-cache'
request.body = "{ \"organization_usage\": \"ORG_USAGE\", \"organization_require_behavior\": \"ORG_REQUIRE_BEHAVIOR\" }"

response = http.request(request)
puts response.read_body
import Foundation

let headers = [
  "content-type": "application/json",
  "authorization": "Bearer MGMT_API_ACCESS_TOKEN",
  "cache-control": "no-cache"
]
let parameters = [
  "organization_usage": "ORG_USAGE",
  "organization_require_behavior": "ORG_REQUIRE_BEHAVIOR"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://YOUR_DOMAIN/api/v2/clients/CLIENT_ID")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

Value Description
CLIENT_ID ID of the application for which you want to add organization behavior.
MGMT_API_ACCESS_TOKEN Access Tokens for the Management API with the scope update:clients.
ORG_USAGE Dictates whether your application can support users logging into an organization. Options include:
  • deny: (Default) Users cannot log in using an organization.
  • allow: Users can log in either with an organization or without one. When selected, you must provide an organization when you redirect users to the /authorize endpoint.
  • require: Users must log in using an organization. When selected, you must either provide an organization when you redirect users to the /authorize endpoint or set ORG_REQUIRE_BEHAVIOR to pre_login_prompt to allow users to choose an organization before they log in.
ORG_REQUIRE_BEHAVIOR Specifies what type of prompt to use when your application requires that users select their organization. Only applicable when ORG_USAGE is require. Options include:
  • no_prompt: (Default) Display no prompt. Requests without a valid organization parameter will be rejected.
  • pre_login_prompt: Display Auth0’s out-of-box pre-login Organization prompt.

Response status codes

Possible response status codes are as follows:

Status code Error code Message Cause
200 Client successfully updated.
400 invalid_uri Invalid request URI. The message will vary depending on the cause. The path is not valid.
400 invalid_body Invalid request body. The message will vary depending on the cause. The request payload is not valid.
401 Invalid token.
401 Client is not global.
401 Invalid signature received for JSON Web Token validation.
403 insufficient_scope Insufficient scope; expected any of: update:clients. Tried to read/write a field that is not allowed with provided bearer token scopes.
403 insufficient_scope Some fields cannot be updated with the permissions granted by the bearer token scopes. The message will vary depending on the fields and the scopes. Tried to read/write a field that is not allowed with provided bearer token scopes.
403 operation_not_supported The account is not allowed to perform this operation. The account is not allowed to perform this operation.
404 inexistent_client Client not found. Inexistent resource. Specified application does not exist.
429 Too many requests. Check the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.