---
title: "Token Handler First Configuration"
description: "Configure the Curity token handler settings to enable cookie handling endpoints for SPAs."
url: "https://curity.io/resources/learn/token-handler-first-configuration/"
date: "2024-12-01"
area: "tutorials"
topic: "getting-started"
pagegroup: "tokenhandler-getting-started"
---

# Token Handler First Configuration

After completing the [Installation of the Curity Token Handler](https://curity.io/resources/learn/token-handler-getting-started/), use the Admin UI to first perform a basic setup and create the initial configuration. Then, create crypto keys for cookie encryption. Finally, configure the OAuth Agent with the SPA's OAuth confidential client settings and the authorization server's endpoints.

## Run the Basic Setup Wizard

Log in to the Admin UI using the **admin** user and the password from the installation. For a Docker deployment, browse to the Admin UI at `https://localhost:6749/admin`. Otherwise use the deployed host name and URL. Then run the basic setup wizard to complete the [First Configuration](https://curity.io/resources/learn/first-config/). Select the `Token Handler only` option and upload a license file:

![Configuration Options](https://curity.io/images/resources/tutorials/writing-clients/spa/token-handler-curity/token-handler-configuration.jpg)

Accept all other defaults to complete the wizard. The token handler consists only of stateless API components so there is no need to configure any backend data storage. Use the **Changes** -> **Commit** menu option to save your settings.

## Create Cryptographic Keys

Next, create cryptographic keys that token handler components use for cookie encryption and decryption. Use the OpenSSL tool and run the following commands to create crypto keys. Enter an encryption password when prompted.

```bash
openssl ecparam -name prime256v1 -genkey -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem
openssl pkcs8 -topk8 -in private-key.pem -out private-key.pkcs8
```

## Configure the OAuth Agent

Next, use the Admin UI to create a token handler application that uses the cryptographic keys. Navigate to **Profiles** -> **Applications** and click on **New Token Handler Application**. Assign an ID to describe the SPA which becomes part of the base URL of the OAuth Agent.

![Token Handler Application](https://curity.io/images/resources/tutorials/writing-clients/spa/token-handler-curity/token-handler-application.jpg?v=20261026)

Next, edit the token handler application settings. The left hand side shows OAuth Agent settings and the right hand side shows OAuth Proxy settings. If you have an existing authorization server, select the `Use External OAuth Server` option.

![Token Handler Application Settings](https://curity.io/images/resources/tutorials/writing-clients/spa/token-handler-curity/token-handler-application-settings.jpg?v=20261026)

The OAuth Agent acts a confidential client for the SPA. Therefore, configure the OAuth Agent with client settings and the endpoints of the authorization server. Enter values similar to those in the following table. The configuration used during development might use HTTP URLs and include a port number in redirect URIs. Learn more about ways to configure the OAuth Agent in the [Create a Token Handler](https://curity.io/resources/learn/curity-token-handler/) tutorial.

| Field | Value |
| --- | --- |
| Client ID | spa-client |
| Client Secret | m8v7y0JH1SC |
| Redirect URI | `https://www.demoapp.example/callback` |
| Authorization Endpoint | `https://login.example.com.com/oauth/v2/authorization` |
| Token Endpoint | `https://login.example.com.com/oauth/v2/token` |
| Token Issuer | `https://login.example.com` |
| Scopes | openid |
| Use PKCE | On |
| Logout | On |
| Logout Endpoint | `https://login.example.com.com/oauth/v2/logout` |
| Post Logout Redirect URI | `https://www.demoapp.example` |

Next, on the right hand side, use the **Upload** button to save the `public-key.pem` file from the generated crypto keys. The OAuth Agent uses this key when it encrypts the cookie that the SPA sends to APIs. Select the **Changes** -> **Commit** button to save the configuration.

### Test the OAuth Agent

After installation and configuration, you can call OAuth Agent endpoints using a path of the form `/apps/example`, where `example` is the name of the token handler application created earlier. After a default Docker installation with the example configuration settings from the above table, you can run the following command to call the OAuth Agent and start a flow:

```bash
curl -i -X POST http://localhost:8443/apps/example/login/start \
    -H 'origin: https://www.demoapp.example' \
    -H 'token-handler-version: 1'
```

The response from the OAuth Agent includes an authorization request URL. An SPA uses this URL to initiate a login:

```json
{
  "authorization_url": "https://login.example.com/oauth/v2/authorization?client_id=myclient&response_type=code ..."
}
```

## Integrate with the API Gateway

The final deployment related task is to make the token handler's endpoints available at a domain based URL that the SPA can call. To enable that, you [Integrate with the API Gateway](https://curity.io/resources/learn/token-handler-integrate-gateway/).
