3 mins read

Using Application Metadata in Token Claims

This article provides an instruction on how to add application metadata to ID or access tokens in Cloudentity to provide application's data used to perform authorization decisioning and enforcement.

About Using Client Metadata

With Cloudentity, you can inject additional metadata attributes as part of the client application object.

Metadata can be used as


  • Administrator’s privileges in Cloudentity

  • At least one application with its metadata defined in Cloudentity


    • For the purpose of this instruction, the Demo Portal application is used (built-in by default in the Cloudentity administrator portal).

    • For the instruction on how to add metadata for an application, see Configure app metadata.

Create Custom Token Claims

You can create a new claim for your tokens using client metadata

Use the Admin Portal

To enhance your tokens with claims using application metadata, you can either see the short video guide or follow the step-by-step instruction.

Video Guide

Step-by-step Instruction

  1. Navigate to Cloudentity and sign in to your account.

  2. Go to Auth Settings > Tokens > Claims.

  3. Select the type of the token that you want to enhance (ID Tokens or Access Tokens) and Add claim.

  4. In the Add claim pop-out window

    • Enter a name of the claim.
    • Select Client from the Source type drop-down menu.
    • From the Source path drop-down menu, select Metadata to specify the path to the data object that you want to inject.
  5. Select Create from the bottom of the Add claim pop-out window.


You have added a new custom claim for your tokens.


See Verify the new token claim to check how to test your new setup.

Use Admin Api

To create your custom token claim, use the Create claim admin API to make a CURL call with option --data-raw posting required data to the server.


Make sure that tenant_id, authorization_server_id, and Cloudentity URL are correct. This API requires the tenant-admin-level access token.

Example CURL Call

curl --location --request POST '' \
--header 'Authorization: Bearer <Admin Access Token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"tenant_id": "your-acp-tenant",
"authorization_server_id": "your-acp-workspace",
"name": "application_labels",
"mapping": "metadata",
"source_type": "client",
"source_path": "metadata.application_labels",
"type": "access_token",
"scopes": []

Verify New Token Claim

If you use the Cloudentity administrator portal to add your new custom token claim, you can check if the claim is actually added to your token using the demo application built in the Cloudentity administrator portal and available by default.

Step-by-step Guide

  1. Navigate to Cloudentity and sign in to your account.

  2. Open the Demo application.

  3. Log in to the demo application.


You have logged in to Demo application and you can check the tokens issued by Cloudentity. In particular, you can verify Access token > PAYLOAD for your newly-added claim.

Updated: Jul 19, 2022