Edge Route OAuth Module

Replace HTTPS Edge Route OAuth Module

Request

PUT /edges/https/{edge_id}/routes/{id}/oauth

Example Request

curl \
-X PUT \
-H "Authorization: Bearer {API_KEY}" \
-H "Content-Type: application/json" \
-H "Ngrok-Version: 2" \
-d '{"enabled":true,"provider":{"google":{"client_id":"client-id","client_secret":"client-secret","email_addresses":["alan@example.com"],"scopes":["profile","email","https://www.googleapis.com/auth/userinfo.email"]}}}' \
https://api.ngrok.com/edges/https/edghts_2k5okVDrNTABnbYmAOElkKovm8D/routes/edghtsrt_2k5okXZeIhP3Ok04RKv9hIbn5wg/oauth

Parameters

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
provider	EndpointOAuthProvider	an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval	uint32	Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.

EndpointOAuthProvider parameters

Name	Type	Description
github	EndpointOAuthGitHub	configuration for using github as the identity provider
facebook	EndpointOAuthFacebook	configuration for using facebook as the identity provider
microsoft	EndpointOAuthMicrosoft	configuration for using microsoft as the identity provider
google	EndpointOAuthGoogle	configuration for using google as the identity provider
linkedin	EndpointOAuthLinkedIn	configuration for using linkedin as the identity provider
gitlab	EndpointOAuthGitLab	configuration for using gitlab as the identity provider
twitch	EndpointOAuthTwitch	configuration for using twitch as the identity provider
amazon	EndpointOAuthAmazon	configuration for using amazon as the identity provider

EndpointOAuthGitHub parameters

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams	List<string>	a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations	List<string>	a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'

EndpointOAuthFacebook parameters

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft parameters

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle parameters

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthLinkedIn parameters

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

EndpointOAuthGitLab parameters

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

EndpointOAuthTwitch parameters

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

EndpointOAuthAmazon parameters

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

Response

Returns a 200 response on success

Example Response

{
	"auth_check_interval": 0,
	"cookie_prefix": "ngrok.",
	"enabled": true,
	"inactivity_timeout": 0,
	"maximum_duration": 0,
	"options_passthrough": false,
	"provider": {
		"amazon": null,
		"facebook": null,
		"github": null,
		"gitlab": null,
		"google": {
			"client_id": "client-id",
			"client_secret": "client-secret",
			"email_addresses": ["alan@example.com"],
			"email_domains": [],
			"scopes": [
				"profile",
				"email",
				"https://www.googleapis.com/auth/userinfo.email"
			]
		},
		"linkedin": null,
		"microsoft": null,
		"twitch": null
	}
}

Fields

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
provider	EndpointOAuthProvider	an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval	uint32	Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.

EndpointOAuthProvider fields

Name	Type	Description
github	EndpointOAuthGitHub	configuration for using github as the identity provider
facebook	EndpointOAuthFacebook	configuration for using facebook as the identity provider
microsoft	EndpointOAuthMicrosoft	configuration for using microsoft as the identity provider
google	EndpointOAuthGoogle	configuration for using google as the identity provider
linkedin	EndpointOAuthLinkedIn	configuration for using linkedin as the identity provider
gitlab	EndpointOAuthGitLab	configuration for using gitlab as the identity provider
twitch	EndpointOAuthTwitch	configuration for using twitch as the identity provider
amazon	EndpointOAuthAmazon	configuration for using amazon as the identity provider

EndpointOAuthGitHub fields

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams	List<string>	a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations	List<string>	a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'

EndpointOAuthFacebook fields

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft fields

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle fields

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthLinkedIn fields

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

EndpointOAuthGitLab fields

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

EndpointOAuthTwitch fields

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

EndpointOAuthAmazon fields

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

Get HTTPS Edge Route OAuth Module

Request

GET /edges/https/{edge_id}/routes/{id}/oauth

Example Request

curl \
-X GET \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_2k5okVDrNTABnbYmAOElkKovm8D/routes/edghtsrt_2k5okXZeIhP3Ok04RKv9hIbn5wg/oauth

Response

Returns a 200 response on success

Example Response

{
	"auth_check_interval": 0,
	"cookie_prefix": "ngrok.",
	"enabled": true,
	"inactivity_timeout": 0,
	"maximum_duration": 0,
	"options_passthrough": false,
	"provider": {
		"amazon": null,
		"facebook": null,
		"github": null,
		"gitlab": null,
		"google": {
			"client_id": "client-id",
			"client_secret": "client-secret",
			"email_addresses": ["alan@example.com"],
			"email_domains": [],
			"scopes": [
				"profile",
				"email",
				"https://www.googleapis.com/auth/userinfo.email"
			]
		},
		"linkedin": null,
		"microsoft": null,
		"twitch": null
	}
}

Fields

Name	Type	Description
enabled	boolean	true if the module will be applied to traffic, false to disable. default true if unspecified
provider	EndpointOAuthProvider	an object which defines the identity provider to use for authentication and configuration for who may access the endpoint
options_passthrough	boolean	Do not enforce authentication on HTTP OPTIONS requests. necessary if you are supporting CORS.
cookie_prefix	string	the prefix of the session cookie that ngrok sets on the http client to cache authentication. default is 'ngrok.'
inactivity_timeout	uint32	Integer number of seconds of inactivity after which if the user has not accessed the endpoint, their session will time out and they will be forced to reauthenticate.
maximum_duration	uint32	Integer number of seconds of the maximum duration of an authenticated session. After this period is exceeded, a user must reauthenticate.
auth_check_interval	uint32	Integer number of seconds after which ngrok guarantees it will refresh user state from the identity provider and recheck whether the user is still authorized to access the endpoint. This is the preferred tunable to use to enforce a minimum amount of time after which a revoked user will no longer be able to access the resource.

EndpointOAuthProvider fields

Name	Type	Description
github	EndpointOAuthGitHub	configuration for using github as the identity provider
facebook	EndpointOAuthFacebook	configuration for using facebook as the identity provider
microsoft	EndpointOAuthMicrosoft	configuration for using microsoft as the identity provider
google	EndpointOAuthGoogle	configuration for using google as the identity provider
linkedin	EndpointOAuthLinkedIn	configuration for using linkedin as the identity provider
gitlab	EndpointOAuthGitLab	configuration for using gitlab as the identity provider
twitch	EndpointOAuthTwitch	configuration for using twitch as the identity provider
amazon	EndpointOAuthAmazon	configuration for using amazon as the identity provider

EndpointOAuthGitHub fields

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint
teams	List<string>	a list of github teams identifiers. users will be allowed access to the endpoint if they are a member of any of these teams. identifiers should be in the 'slug' format qualified with the org name, e.g. org-name/team-name
organizations	List<string>	a list of github org identifiers. users who are members of any of the listed organizations will be allowed access. identifiers should be the organization's 'slug'

EndpointOAuthFacebook fields

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthMicrosoft fields

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthGoogle fields

Name	Type	Description
client_id	string	the OAuth app client ID. retrieve it from the identity provider's dashboard where you created your own OAuth app. optional. if unspecified, ngrok will use its own managed oauth application which has additional restrictions. see the OAuth module docs for more details. if present, client_secret must be present as well.
client_secret	string	the OAuth app client secret. retrieve if from the identity provider's dashboard where you created your own OAuth app. optional, see all of the caveats in the docs for client_id.
scopes	List<string>	a list of provider-specific OAuth scopes with the permissions your OAuth app would like to ask for. these may not be set if you are using the ngrok-managed oauth app (i.e. you must pass both client_id and client_secret to set scopes)
email_addresses	List<string>	a list of email addresses of users authenticated by identity provider who are allowed access to the endpoint
email_domains	List<string>	a list of email domains of users authenticated by identity provider who are allowed access to the endpoint

EndpointOAuthLinkedIn fields

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

EndpointOAuthGitLab fields

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

EndpointOAuthTwitch fields

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

EndpointOAuthAmazon fields

Name	Type	Description
client_id	string
client_secret	string
scopes	List<string>
email_addresses	List<string>
email_domains	List<string>

Delete HTTPS Edge Route OAuth Module

Request

DELETE /edges/https/{edge_id}/routes/{id}/oauth

Example Request

curl \
-X DELETE \
-H "Authorization: Bearer {API_KEY}" \
-H "Ngrok-Version: 2" \
https://api.ngrok.com/edges/https/edghts_2k5okVDrNTABnbYmAOElkKovm8D/routes/edghtsrt_2k5okXZeIhP3Ok04RKv9hIbn5wg/oauth

Response

Returns a 204 response with no body on success