# Synchronous

{% embed url="<https://www.loom.com/share/Setting-up-an-Extension-to-Add-Custom-Claims-to-Tokens-9645b80d03f4423e98984e2bdda0eb78?sid=19eaefe1-5c4e-4ca4-b3ff-3bd0edeaed16>" %}
Setting up an extension to add custom claims to tokens in the Quasr Tenant Admin UI.
{% endembed %}

Extensions used for injecting custom claims in ID and/or access tokens are run synchronous. In this section we describe the event payload and required response format. If your extension runs into an error or times out it will simply be ignored.

{% hint style="warning" %}
Your extension **can run up to 5 seconds** though the overall process behind the relevant OAuth 2.0 endpoints will also time out after 10 seconds hence you should anticipate you need to return claims faster.
{% endhint %}

## Configuration

Synchronous extensions are configured as part of the respective resource.

<figure><img src="/files/dUcfKlQQJmQ714oITR7m" alt=""><figcaption><p>Configuration of token extensions in client OAuth 2.0 configuration under Accounts in the Quasr Tenant Admin UI.</p></figcaption></figure>

## Events

### OAuth 2.0 Authorize Endpoint

```json
{
    "type": "CUSTOMIZATION",
    "origin": "<client_id>", // client requesting token
    "action": "create-token",
    "account_id": "<account_id>", // subject of the token
    "tenant_id": "<tenant_id>" // tenant ID
    "source": "quasr.tokens/oauth2/authorize",
    "result": "PENDING",
    "detail": {
        "source": "oauth2/authorize",
        "type": "oidc1:id", // ID token
        "claims": [] // list of consented claims
    }
}
```

### OAuth 2.0 Token Endpoint

```json
{
    "type": "CUSTOMIZATION",
    "origin": "<client_id>", // client requesting token
    "action": "create-token",
    "account_id": "<account_id>", // subject of the token
    "tenant_id": "<tenant_id>" // tenant ID
    "source": "quasr.tokens/oauth2/authorize",
    "result": "PENDING",
    "detail": {
        "source": "oauth2/token",
        "type": "oidc1:id", // ID token
        "claims": [] // list of consented claims
    }
}
```

```json
{
    "type": "CUSTOMIZATION",
    "origin": "<client_id>", // client requesting token
    "action": "create-token",
    "account_id": "<account_id>", // subject of the token
    "tenant_id": "<tenant_id>" // tenant ID
    "source": "quasr.tokens/oauth2/authorize",
    "result": "PENDING",
    "detail": {
        "source": "oauth2/token",
        "type": "oauth2:access", // access token
        "scope": "" // consented scopes separated by spaces
    }
}
```

## Response Format

The response are the custom claims to be injected into the token.

```json
{
    "custom_claim": "<custom_value>",
    ...
}
```

{% hint style="danger" %}
You can't set the following custom claims:

* `nonce` or `client_id` (if already present)
* `iss`, `aud`, `sub`, `iat`, `nbf`, `exp` and `jti`
* any claim starting with `https://api.quasr.io/claims`

Trying to set any of these claims will simply be ignored.
{% endhint %}

## Example: Add Custom Claims to Tokens

Example to add a **custom claim** named `magic` with value `test`:

```javascript
exports.handler = async function() {return { magic: 'test' }}
```

An example that calls an external API to fetch information for enriching tokens - you can use the `fetch` standard library, as the example below shows:

```javascript
exports.handler = async function(event) {
  /*
  if your logic relies on the current account / tenant / client, 
  you can get its values from the event via:
  event.account_id
  event.tenant_id
  event.origin (client ID)
  */
  const response = await fetch('https://swapi.dev/api/people/1')
  const person = await response.json();
  return { "https://my.namespace.com/name": person.name}
}
```

**Code Extensions can be assigned per client**. Within client settings (available via API or Tenant Admin > Accounts > Client > Client Settings > OAuth2 Settings), you can set a code extension to be used for both ID token and/or access token.

If you're using the GraphQL API to assign the extension, you would set the extension's UUID via the following path (the "account" being the "client"): `account.config.id_token_extension` or `account.config.access_token_extension`

<figure><img src="/files/dUcfKlQQJmQ714oITR7m" alt=""><figcaption><p>Setting extensions for adding custom claims to ID or access tokens in the Quasr Tenant Admin UI</p></figcaption></figure>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.quasr.io/quasr/tenant-administration/extensions/synchronous.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.