> ## Documentation Index
> Fetch the complete documentation index at: https://docs.curator.interworks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Registered Embedded Apps

> Sign Curator users in to embedded apps automatically by registering the apps your portal trusts.

An embedded app can verify which Curator user is viewing it by checking a signed identity token named `iw_token`.
The [`[IW_TOKEN]` placeholder](https://docs.curator.interworks.com/site_content_design/pages/manual_embed_iframes#passing-a-verified-identity-with-iw_token)
adds that token to one iFrame URL at a time. When you register an app's origin instead, Curator signs every iFrame
element that points at the app without a placeholder, and scripts in Embed Code (HTML) elements can ask Curator for a
token for the app.

The token is the same one `[IW_TOKEN]` produces, and the embedded app verifies it the same way. The one difference
is the `aud` claim: automatic signing writes the host in lower case and without the default port (`:443` or `:80`),
while `[IW_TOKEN]` uses the host exactly as it is written in the element URL. See
[Passing a verified identity with `[IW_TOKEN]`](https://docs.curator.interworks.com/site_content_design/pages/manual_embed_iframes#passing-a-verified-identity-with-iw_token)
for the token's claims and how to check it against Curator's public keys.

Only register apps you or your team control, and that verify Curator's token. Curator issues tokens for a
registered app to every signed-in user who views a page that embeds it.

## Registering an App

In the [backend of Curator](https://docs.curator.interworks.com/site_administration/accessing_the_backend.md) using the left-hand navigation,
navigate to the
**Settings**
\>
**Security**
\>
**Authentication Settings** page.

On the  page
click the **Security & Access** tab

.

1. Scroll to the **Embedded App Sign-in** section.
2. Under **Registered Embedded Apps**, click **Add an embedded app**.
3. In **Origin**, enter the app's origin, such as `https://forms.example.com`.
4. Optionally, enter a **Name** to help you recognize the app later.
5. Click **Save**.

Only a superuser can change the list of registered embedded apps. Other backend administrators see it locked.

### Origin Format

An origin is the scheme, the host, and an optional port, and nothing else:

| Example | Accepted? |
| - | - |
| `https://forms.example.com` | Yes |
| `https://forms.example.com/` | Yes, the trailing slash is dropped |
| `https://forms.example.com:8443` | Yes, for an app on a non-standard port |
| `https://forms.example.com:443` | Yes, saved as `https://forms.example.com`, since 443 is the https default |
| `forms.example.com` | No, the scheme is missing |
| `https://forms.example.com/form/budget` | No, it has a path |
| `https://forms.example.com?school=12` | No, it has a query string |
| `https://user@forms.example.com` | No, it has a user name |
| `ftp://forms.example.com` | No, only `http://` and `https://` are accepted |

Curator saves each origin in lower case. If any origin is not in this format, the save is refused and Curator shows
which origin it could not accept.

An origin matches a URL only when the scheme, host, and port are all the same. Registering
`https://forms.example.com` does not cover `http://forms.example.com`, `https://forms.example.com:8443`, or
`https://www.forms.example.com`. Register each one you embed.

## Signing iFrame Elements Automatically

When a signed-in user views a page, Curator adds `iw_token=<token>` to the URL of every **iFrame** element that
points at a registered origin. For example, `https://forms.example.com/form?school=12` loads as
`https://forms.example.com/form?school=12&iw_token=<token>`. A fragment such as `#section-2` stays at the end of the
URL.

Curator leaves the URL as it is when:

* The element URL contains the `[IW_TOKEN]` placeholder. The placeholder adds the token instead.
* The URL already has an `iw_token` parameter.
* Nobody is signed in. Anonymous visitors load the plain URL.
* The URL points at an origin that is not registered.

## Signing URLs from an Embed Code (HTML) Element

Placeholders and automatic signing apply only to **iFrame** elements. When a script in an **Embed Code (HTML)**
element builds an iframe URL in the browser, it can sign that URL with the `Curator.embedAuth` helper. Curator adds
the helper to every page once at least one app is registered, so a script in the element can use it right away.
When no app is registered, Curator does not add the helper, so check that it exists first, as the example does.

```html theme={null}
<iframe id="budget-form" width="100%" height="600"></iframe>
<script>
(async function () {
    var schoolId = 12;
    var url = 'https://forms.example.com/form/budget/' + schoolId;
    var signer = window.Curator && window.Curator.embedAuth;
    document.getElementById('budget-form').src = signer ? await signer.signUrl(url) : url;
}());
</script>
```

* `Curator.embedAuth.signUrl(url)` returns the URL with a fresh `iw_token` added, replacing any `iw_token` already
  in it. When the URL cannot be signed, because its origin is not registered, nobody is signed in, or Curator refuses
  the request, it returns the URL unchanged and logs a warning in the browser console. It never fails, so the frame
  still loads and the embedded app can show its own sign-in message.
* `Curator.embedAuth.getToken(host)` returns just the token, for a script that passes it some other way. Pass the
  app's host, such as `forms.example.com` or `forms.example.com:8443`, or a full URL, whose scheme must then match
  the registered origin. When Curator refuses, it fails with an object that has `status`, `code`, and `message`
  properties.

A token expires about a minute after it is issued. Curator does not stop a token from being used twice within that
minute: to accept each token only once, the embedded app has to remember the token's `jti` claim until it expires. Sign
each URL right before you load it, and sign it again for each frame and each reload.

## The Token Endpoint

`Curator.embedAuth` gets its tokens from this endpoint. Scripts on your Curator pages can also call it directly:

```text theme={null}
GET https://<your-curator-host>/user/embedauth/token?audience=<host[:port]>&scheme=https
```

* `audience` is required. It is the app's host, with the port only when the app uses a non-standard one.
* `scheme` is optional, `http` or `https`. When it is given, the registered origin must use that scheme.

The endpoint uses the visitor's Curator session to decide who the token is for, so it only answers requests from
pages on your Curator portal. It does not allow requests from other websites. If Curator is hosted under a base path,
include it, such as `https://<host>/<basepath>/user/embedauth/token`.

Every response is JSON:

* **200**: the token was issued.

  ```json theme={null}
  {"token": "<jwt>", "audience": "<host[:port]>", "expires_at": 1795000000, "expires_in": 60}
  ```

  `expires_at` is the token's expiry in Unix seconds, and `expires_in` is the number of seconds left until then.
* **401** `{"error": "not_signed_in"}`: nobody is signed in, or the user has not finished multi-factor
  authentication.
* **403** `{"error": "cross_site_request"}`: the browser reported that the request came from another website.
* **404** `{"error": "unregistered_audience"}`: `audience` is missing or is not a registered app, under the given
  `scheme` when one is given.
* **429** `{"error": "rate_limited"}`: the user asked for more than 30 tokens in one minute. The `Retry-After` header
  says how many seconds to wait.
* **500** `{"error": "signing_failed"}`: Curator could not sign the token. The reason is written to the Curator log.

The token's `aud` claim is the `audience` value, the app's `host` or `host:port` in lower case. The embedded app
should confirm that `aud` matches its own host before it trusts the token.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.