Custom OAuth 101

Using Gelato's Single Sign On functionality, you can let your Developers login and register on your portal with their existing user accounts for your service. This is a great integrated Developer Experience, and it also helps when provisioning API Credentials (as now you can associate them with the correct user account)

Plus, you get a great looking branded Login button:

71mdu8ccws  M07

For a Custom OAuth setup, you will need the following:

  • A Gelato Enterprise account (Request a Demo if you haven't already)
  • An OAuth Provider (this means users can authenticate with your app via 3-legged OAuth, usually the Authorization Code Grant. The OAuth Bible site has more information.
  • A User Information Endpoint that can be accessed with an OAuth Token (more on that below)

User Flow

Here's what the whole process looks like :arrow_lower_left:

Sso Flow

First, Gelato will do an OAuth Authorize redirect to your app, which will present a login page the user. Once they've successfully logged in, you'll redirect back to Gelato and we'll get the user's OAuth Access Token. Gelato will then make a request to your User Information Endpoint (authenticated using that access token) to get some JSON details.

Lastly (but very much not leastly!) we can show your Developer their details (including their avatar!) from your system. Amazing! :sparkles: :fireworks:

User Information Endpoint

In order to present information about your Developer, we need an API endpoint we can use to get their basic information. Usually this is something like /user or /me (you can customize the exact path under "Login Methods > Custom OAuth Settings > Advanced")

Your user information endpoint should return JSON like the following (the more details the better!)

  "id":          123,
  "email":       "",
  "name":        "Jason Theape",
  "nickname":    "jase",
  "description": "The Amazing API Ape",
  "avatar":      ""

Setup Steps

Step 1

Create an OAuth Application to use for Gelato SSO. Make a note of the Client ID and Secret for the application. If you need to specify a Redirect URI, use: https://YOUR-PORTAL-DOMAIN/auth/custom/callback (so for, you would use

Step 2

Login to Gelato, and head on over to Portal Settings > Login Methods / SSO, then click "Set Up to Activate" on "Custom OAuth"

Mdotly6zu3  M07

Step 3

Enter your OAuth Application details as per step one (if you're using custom paths, you can set those under "Advanced") You can also customize your button so that it matches your brand here.

Mmswcnvekn  M07

Step 4

Hit "Save & Activate", and you're done! Enjoy your awesome new Custom OAuth. :smile_cat:

3oonso1vy0 M07  1


Please get in touch with support if you have any issues!

Auth0 client connection issue

Recent Auth0 changes have altered the default functionality for OAuth client applications (read more here). Auth0 client applications are now OIDC compliant, but this change breaks Auth0 functionality with Gelato's custom OAuth SSO.

To get around this issue, simply disable the OIDC setting in Auth0:

  • go to the Advanced Settings section of your Auth0 client application
  • select the OAuth tab
  • deselect the OIDC Conformant button and save

Okta client connection issue

Using Okta as an SSO provider for the portal requires that certain scope values are sent as query parameters from Gelato to Okta. When configuring Custom OAuth Settings of Gelato's Portal Settings > Login Methods/SSO section, you will need to pass in the following scopes (at minimum) to OAuth Host:


For example, your OAuth Host field in Gelato should look something like this: