Auth0 Home Blog Docs

Custom Metadata in OIDC /oauth/token response




  • Your product/project/service has an API surface.
  • You want to secure your API surface using Auth0 issued tokens.
  • You want to return additional metadata to the client to help them be successful with your APIs, for example
    • The instance of your API to use for (geo-location, blue/green, a/b testing, etc)
    • The id of the tenant they have logged into
    • etc


  • You could place this information within your access_token but
  • You could place this information within your id_token / /userinfo but
    • Flows like client credentialsdo not yield an id_token
    • id_tokens are no longer optional for clients
  • You could build a discovery API for clients to talk to after obtaining an access_token but
    • You build a single point of failure into your architecture that prohibits API access should it go down
    • It’s not exactly a slick developer experience for 3rd parties you are trying to on-board into your platform


Allow Auth0 tenants to augment the /oauth/token response in Rules and/or Hooks to apply their own custom metadata. For example:

module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token.scope = scope;
  // Modify scopes or add extra claims
  // access_token''] = 'bar';

  // Modify the token_response
  context.token_response'api-uri'] = ''
  cb(null, access_token);

Would yield response from the /oauth/token endpoint of:

    "access_token": "eyJ0eXAiOiJKV1...",
    "expires_in": 86400,
    "scope": "my scopes",
    "token_type": "Bearer",
    // my meta
    "api-uri": ""


Are you suggesting something similar to combining the oauth/token and /userinfo where you could receive the access token (for future calls) and also include the userInfo data in the response? This would be reduce the number of calls in a few places.


Not really, the /userinfo api returns user information associated to the identity in the access_token. If I wanted to short-cut that process I would simply request an id_token in my original authorization request :slight_smile:

But flows like Client Credentials issue access_tokens for Apps/Clients - not users. There is no id_token, /userinfo does not apply and are usually issued to server-side / offline processes.

I’m looking for a solution to provide a the client with additional metadata associated with an access_token regardless of the flow they used to obtain the token.