Upgrading to Authlete 3.0 cannot be done directly to the running Authlete 2.x instance. Instead, a new Authlete 3.0 environment is created and all services and clients are migrated to it. During services and clients migration, optionally access tokens can also be migrated via the Token Migrator. This is a new service introduced to handle token copying and updating from the Authlete 2.2/2.3 environment into the Authlete 3.0 environment which will allow existing tokens issued in the Authlete 2.2/2.3 environment to be valid and usable in the new Authlete 3.0 environment. See Migrating Tokens to Authlete 3.0 for details.

Migrating using the Configuration Migrator (Dedicated and Self-Managed)

Downloading the Configuration Migrator

Steps 1 to 4 below are performed on the Authlete Shared environment (console.authlete.com), not on the destination environment. The organization and token you create there are used only to pull the image, and are separate from the destination environment’s credentials in the Preparation section below.

To access the container image from the Authlete registry, follow these steps:

1. Create an Organization

Log in to the Authlete Management Console.
Create an organization for your company.
Note down the Organization ID.

Authlete Management Console Create Organization dialog

Organization creation page

2. Request Access

Share the Organization ID and Organization Name with Authlete Support.
Authlete will authorize registry access for your organization.

3. Generate a Registry Access Token

In the Authlete Management Console, generate a Token for your organization with the Read Only permission preset.
This token is used only for docker login. Do not use it as the V3_ORG_ACCESS_TOKEN environment variable of the configuration migrator.
Keep the Organization ID and Token handy for authentication.

Organization Access Tokens section

Add an Organization Access Token dialog with the Read Only permission preset selected

Token creation dialog

4. Authenticate and Pull Images

# Authenticate to Authlete registry
docker login artifacts.authlete.com -u "${SHARED_ORGANIZATION_ID}" -p "${SHARED_ORGANIZATION_ACCESS_TOKEN}"

# Pull the image
docker pull artifacts.authlete.com/configuration-migrator:1.1

Preparation

In order to begin migrating service and client configuration, you will need a running 2.2/2.3 source environment, and another running Authlete 3.0 destination environment. Each value below is set in the configuration migrator as the environment variable named next to it (see Migration Settings). From your 2.2/2.3 source environment:

The API URL of the environment (e.g. https://api.source-environment): used for V2_API_URL
Your Service Owner API Key, found in the Your Account page in the Service Owner Console: used for V2_SO_API_KEY
Your Service Owner API Secret, found in the Your Account page in the Service Owner Console: used for V2_SO_API_SECRET

The Your Account page of the Service Owner Console, with the Your Account menu item, API Key and API Secret highlighted (values masked)

Your Account page in the Service Owner Console From your 3.0 destination environment:

The API URL of the environment (e.g. https://api.destination-environment): used for V3_API_URL
The API server ID of the server that the services and clients will be imported in, and the ID of the organization that they will be created in: used for V3_API_SERVER_ID and V3_ORG_ID
- Select the cluster from the cluster drop-down in the console navigation bar. The page then shows the API server ID as Cluster ID under Cluster Information, and the organization ID as Organization ID under Organization Overview
API server ID (Cluster ID) and organization ID (Organization ID)
Your IdP URL (e.g. https://login.destination-environment): used for V3_IDP_URL
Your Organization Access Token for the organization that the services and clients will be created in: used for V3_ORG_ACCESS_TOKEN
- Can be issued from the Organization Settings page under the General tab of the 3.0 destination environment’s console and must be created with the create_service and modify_service permissions
- It is a different token from the registry access token used to pull the image
Organization access token for the destination environment

Prerequisites for Migrating Dynamically Registered Clients

If you plan on migrating dynamically registered clients (RFC 7591), then you must have the following versions deployed to your environments and enable the appropriate feature flags in order for the migration endpoints for dynamically registered clients to be available. On Dedicated environments, contact Authlete support and request for these features to be enabled. On self-managed environments, deploy these versions and enable the feature flags yourself.

For 2.2 source environments - Version 2.2.65+ must be deployed and the feature flag DCR_RAT_ENDPOINT must be enabled
For 2.3 source environments - LTS Version 2.3.51+ must be deployed and the feature flag DCR_RAT_ENDPOINT must be enabled
For 3.0 destination environments - Version 3.0.36+ must be deployed and the feature flag MIGRATE_CLIENT_DCR_ENDPOINT must be enabled

How the Configuration Migrator Works

When it runs, the configuration-migrator performs the following steps:

It will fetch services/clients from the 2.2/2.3 source environment
For each of the services, it will check if the service already exists, and if not will create a service in the 3.0 environment via the IdP
For each client within the service, it will check whether the client already exists, and if not will create the client in the 3.0 environment
(If client secret migration is enabled) Whether the client was newly created or not, it will check and align the client secret credential, updating the 3.0 environment with the client secret value from the 2.2/2.3 source environment
(If dynamically registered client migration is enabled and the source client is a dynamically registered client) If the matching destination client is not already configured as a dynamically registered client, then it will finalize the client’s configuration and set their registration access token from the 2.2/2.3 source client
(If client deletion is enabled) It will delete destination clients that no longer exist in the 2.2/2.3 source environment

By default, the migrator runs once and exits. Services and clients that already exist in the destination environment are not created again, but the client secrets and dynamic client registration configuration of existing clients are still aligned (steps 4 and 5). Other configuration on existing services and clients is not updated.

Migration Settings

Once the 3.0 destination environment is running, the configuration-migrator can be used to move service and client configuration from your 2.2/2.3 source environment to your 3.0 destination environment. If you migrate dynamically registered clients, first deploy the Authlete versions and enable the feature flags listed in Prerequisites for Migrating Dynamically Registered Clients. The configuration-migrator performs this migration entirely through the Authlete APIs, so it will require environment endpoint and API credentials in order to successfully migrate the service and client configuration.

Available Settings

Required Settings

Environment Variable	Type	Description
`V2_API_URL`	URL	The base URL to the 2.2/2.3 source environment `server`.
`V2_SO_API_KEY`	String	The service owner “API Key” from the 2.2/2.3 source environment. Found in the “Your Account” page in the Service Owner Console.
`V2_SO_API_SECRET`	String	The service owner “API Secret” from the 2.2/2.3 source environment. Found in the “Your Account” page in the Service Owner Console.
`V3_API_URL`	URL	The base URL to the 3.0 destination environment `server`.
`V3_API_SERVER_ID`	Number	The API server ID of the server that you would like to import the services and clients into.
`V3_IDP_URL`	URL	The base URL to the 3.0 destination environment IdP.
`V3_ORG_ACCESS_TOKEN`	String	The organization token for the organization that the migrated services and clients should be created within.
`V3_ORG_ID`	Number	The organization ID of the organization that the migrated services and clients should be created within.

Optional Settings

Environment Variable	Type	Description	Default Value
`DRY_RUN`	Boolean	When enabled the migrator will be placed into dry run mode where only API retrieval actions will be performed. No new services or clients will be created, no client secrets will be updated and no clients will be deleted. All intended actions will be logged to understand what the migrator will execute when dry run is disabled.	false
`SYNC_CLIENT_TOKENS`	Boolean	When enabled newly imported clients will have the `inScopeForTokenMigration` property set to `true`. This will allow the Token Migrator to begin token migration from these clients if it is running. Having this flag enabled for clients in the 3.0 destination environment is a pre-condition for token migration so it is recommended to keep this enabled unless you do not intend to migrate tokens.	true
`MIGRATE_CLIENT_SECRETS`	Boolean	When enabled client’s secrets will be migrated and updated in the 3.0 destination environment to match the client secret from the 2.2/2.3 source environment. Clients having the same client secret is a pre-condition for token migration so it is recommended to keep this enabled unless you do not intend to migrate tokens.	true
`MIGRATE_DCR_CLIENTS`	Boolean	When enabled dynamically registered clients from the source APIs will be migrated to the destination environment. The registration access token hash will be configured into the newly created destination client. If this setting is disabled dynamically registered clients will be skipped and not created in the destination environment.	true
`SERVICE_IDS`	Number[]	Expected as a comma-separated list of service IDs. E.g. `12345,67891`. This property is used to filter and only perform migration on services whose ID is in this list along with the clients in these services. If this property is left empty then all services in the 2.2/2.3 source environment under the provided service owner account will be migrated.	[]
`MAX_V2_RPS`	Number	The maximum requests per second (RPS) that the migrator will perform against the source 2.2/2.3 API as part of the migration. All outbound requests to the 2.2/2.3 API will not exceed this limit.	5.0
`MAX_V3_RPS`	Number	The maximum requests per second (RPS) that the migrator will perform against the destination 3.0 API as part of the migration. All outbound requests to the 3.0 API will not exceed this limit.	5.0
`RETRY_MAX`	Number	The maximum amount of retry attempts per endpoint.	5
`RETRY_BASE_DELAY`	Number	The base delay value used when calculating the backoff period between each retry. This value is in seconds.	1.0
`OUTPUT_DIR`	String (Path)	The migration summary output directory, mapped to `/app/migration-output` inside the container.	”./migration-output”
`CONTINUOUS_SYNC`	Boolean	When enabled, the migrator repeats the migration in a loop until it is stopped, creating new services and clients and checking client secrets and dynamic client registration configuration on each cycle. When disabled, the migrator runs once and exits.	false
`SYNC_CLIENT_DELETION`	Boolean	When enabled, clients in the destination environment that do not exist in the source environment are deleted, including clients created directly in the destination.	false
`SYNC_INTERVAL_SECONDS`	Number	The number of seconds to wait between synchronization cycles. Only applies when `CONTINUOUS_SYNC` is enabled.	5
`CLIENT_LIST_REQUEST_COUNT`	Number	The number of clients requested per page from the source and destination client list APIs. Change this only if the client list API in your environment is configured to return a different maximum number of clients per page.	100

When CONTINUOUS_SYNC is enabled, the migrator repeats steps 1–6 of How the Configuration Migrator Works in a loop, waiting SYNC_INTERVAL_SECONDS between cycles. Each cycle only creates services and clients that are new in the source environment, and checks that existing clients’ secrets and dynamic client registration configuration are correctly configured (when the corresponding settings are enabled). If SYNC_CLIENT_DELETION is enabled, each cycle also deletes destination clients that no longer exist in the source environment. The migrator keeps running until you stop the container (see Running the Migration).

CONTINUOUS_SYNC, SYNC_CLIENT_DELETION, SYNC_INTERVAL_SECONDS and CLIENT_LIST_REQUEST_COUNT are available in configuration-migrator 1.1 or later.

Migration Steps

We recommend running the migration in dry run mode first to confirm the expected migration changes and then run again with dry run mode disabled to perform the migration.

If you plan to use the zero downtime (parallel cutover) approach, deploy the changes to your authorization server before you run the migration in step 4.

1. Confirm Environments Are Set Up and Running

Confirm that the 2.2/2.3 source environment and 3.0 destination environment APIs are available from the configuration-migrator’s environment.

2. Set Up the Configuration Migrator

Using the tables outlined above, configure the configuration-migrator with the appropriate properties, including the correct endpoints, credentials and service/organization IDs. Below is a sample Docker Compose configuration with dry run enabled (DRY_RUN=true). In dry run mode the migrator reads from both environments and logs what it would do, but does not perform any creation or write operations. The sample reads each setting from an environment variable of the same name, such as V2_API_URL and V3_ORG_ACCESS_TOKEN. Set them in your shell or in a .env file next to the Compose file before running it.

name: configuration-migrator-sample
services:
  configuration-migrator:
    image: artifacts.authlete.com/configuration-migrator:1.1
    volumes:
      - ./migration-output:/app/migration-output
    environment:
      # API / required configuration
      - V2_API_URL=${V2_API_URL} # e.g. https://api.source-environment
      - V2_SO_API_KEY=${V2_SO_API_KEY}
      - V2_SO_API_SECRET=${V2_SO_API_SECRET}
      - V3_API_URL=${V3_API_URL} # e.g. https://api.destination-environment
      - V3_API_SERVER_ID=${V3_API_SERVER_ID}
      - V3_ORG_ID=${V3_ORG_ID}
      - V3_ORG_ACCESS_TOKEN=${V3_ORG_ACCESS_TOKEN}
      - V3_IDP_URL=${V3_IDP_URL}

      # Migration Options
      - DRY_RUN=true

      # - SERVICE_IDS=${SERVICE_IDS} # Un-comment and set service IDs (e.g. 12345,67891) if you do not wish to migrate all services available to the service owner

      # Continuous Sync Options
      # - CONTINUOUS_SYNC=true # Un-comment to keep synchronizing services and clients until the migrator is stopped
      # - SYNC_INTERVAL_SECONDS=5 # Seconds to wait between synchronization cycles when continuous sync is enabled

Please note that the mounted volumes directory will be used to write output summary files. The container runs as UID 1000 so the host directory must be writable by that user.

When SYNC_CLIENT_DELETION is enabled (true), the migrator deletes clients from the destination environment that do not exist in the source environment, including clients that were created directly in the destination rather than migrated from the source. Deletion happens in a single run as well as in continuous sync mode. Before you enable it for the real migration, check which clients would be deleted with the dry run in step 3.

3. Running in Dry Run Mode

Run the migrator with DRY_RUN=true and capture the log output:

docker compose up 2>&1 | tee dry-run-migration.log

Leave CONTINUOUS_SYNC disabled for the dry run so that the migrator runs once and exits. Once execution is complete, review the log output. No services or clients have been migrated at this point, but the logs show what will be created, updated and deleted when the migrator is run with dry run disabled. If you plan to enable SYNC_CLIENT_DELETION, enable it for the dry run as well and check the logs for [DRY RUN] Removed destination client … lines, which list the clients that would be deleted.

4. Running the Migration

When you are ready to perform the real migration, set DRY_RUN=false in the Docker Compose file and run the migrator again, capturing the log output:

docker compose up 2>&1 | tee migration.log

With dry run disabled, the migrator creates services and clients and updates client secrets in the destination environment. If SYNC_CLIENT_DELETION is enabled, it also deletes destination clients that do not exist in the source environment. If CONTINUOUS_SYNC is enabled, the migrator does not exit after the first cycle. Stop the container (for example, with docker compose stop) once you are sure no further clients are being registered in the source environment. If SYNC_CLIENT_DELETION is also enabled, stop it before any clients are registered in the destination environment, for example before you switch your applications to the 3.0 environment; otherwise each cycle deletes those clients. The migrator prints the full summary when it stops.

5. Checking the Result

The main indicator confirming that the migration was completed successfully is the Errors count being set to 0. The migrator logs each operation while it runs and prints a summary for each service at the end, followed by an overall summary. The summary shows the status of each service (serviceStatus), the number of services processed, clients created, dynamically registered clients updated, client secrets updated and the number of clients deleted (if client deletion is enabled). Errors for individual services or clients appear in the log above the summary. You can safely rerun the migrator, for example if it stopped unexpectedly because of network issues: services and clients that already exist in the destination are not created again, and client secrets are realigned. If SYNC_CLIENT_DELETION is enabled, a rerun also deletes destination clients that do not exist in the source environment. You can also rerun the migrator after a successful migration to confirm that everything was migrated correctly. The sample output below shows an example service summary and overall migration summary for two services:

My Service (apiKey=309958490093)
- A newly created service (denoted by serviceStatus=created)
- With a total of 1241 clients created and migrated
- 612 of the total 1241 clients were dynamically registered clients, so they also were successfully updated further as part of the dynamically registered client migration path
- Since all clients are new, all of their client secrets are updated (Client secrets synced: 1241)
- As the service is new, there are no destination clients to delete (Clients deleted: 0)
Another Service (apiKey=309958490091)
- An existing service (serviceStatus=already_exists)
- 121 new clients were detected in this service and migrated to the destination environment
- 5 of the total 121 clients were dynamically registered clients, so they also were successfully updated further as part of the dynamically registered client migration path
- All clients were new, so all of their secrets were updated (Client secrets synced: 121)
- 3 clients existed in the destination environment but not in the source environment, so they were deleted (Clients deleted: 3)

The overall summary includes the total services and clients processed along with totals for all of the events captured in the service level reports.

2026-09-29 06:56:55 [INFO] ============================================================
2026-09-29 06:56:55 [INFO] Service Summaries
2026-09-29 06:56:55 [INFO] ============================================================
2026-09-29 06:56:55 [INFO] Service name: My Service (apiKey=309958490093) serviceStatus=created overallStatus=OK
2026-09-29 06:56:55 [INFO] ------------------------------------------------------------
2026-09-29 06:56:55 [INFO] Total clients in service: 1241
2026-09-29 06:56:55 [INFO]   Clients created: 1241
2026-09-29 06:56:55 [INFO]   DCR clients updated: 612
2026-09-29 06:56:55 [INFO]   Client secrets synced: 1241
2026-09-29 06:56:55 [INFO] Client deletion sync:
2026-09-29 06:56:55 [INFO]   Clients deleted: 0
2026-09-29 06:56:55 [INFO] Errors: 0
2026-09-29 06:56:55 [INFO] ------------------------------------------------------------
2026-09-29 06:56:55 [INFO] Service name: Another Service (apiKey=309958490091) serviceStatus=already_exists overallStatus=OK
2026-09-29 06:56:55 [INFO] ------------------------------------------------------------
2026-09-29 06:56:55 [INFO] Total clients in service: 121
2026-09-29 06:56:55 [INFO]   Clients created: 121
2026-09-29 06:56:55 [INFO]   DCR clients updated: 5
2026-09-29 06:56:55 [INFO]   Client secrets synced: 121
2026-09-29 06:56:55 [INFO] Client deletion sync:
2026-09-29 06:56:55 [INFO]   Clients deleted: 3
2026-09-29 06:56:55 [INFO] Errors: 0
2026-09-29 06:56:55 [INFO] ------------------------------------------------------------
2026-09-29 06:56:55 [INFO] ============================================================
2026-09-29 06:56:55 [INFO] Migration Summary
2026-09-29 06:56:55 [INFO] ============================================================
2026-09-29 06:56:55 [INFO] ------------------------------------------------------------
2026-09-29 06:56:55 [INFO] Total services processed: 2
2026-09-29 06:56:55 [INFO] Total clients processed: 1362
2026-09-29 06:56:55 [INFO]   Created clients: 1362 (skipped 0, failed 0)
2026-09-29 06:56:55 [INFO]   DCR clients updated: 617/617 created (0 skipped, failed 0)
2026-09-29 06:56:55 [INFO]   Client secrets synced: 1362/1362 (0 skipped, failed 0)
2026-09-29 06:56:55 [INFO] Client deletion sync:
2026-09-29 06:56:55 [INFO]   Clients deleted: 3/3 (0 skipped, failed 0)
2026-09-29 06:56:55 [INFO] Errors: 0
2026-09-29 06:56:55 [INFO] Report saved to /app/migration-output/configuration-migration-report-1790665015.json

When CONTINUOUS_SYNC is enabled, the migrator also prints a one-line iteration summary for each service at the end of every cycle. When the container is stopped, it prints the full summary covering every cycle run up to that point. In this mode the overall migration summary also shows an Iteration count, and lists only the total for each event, without the attempted, skipped and failed counts shown in the sample above. An output sample of the iteration logs is below containing the event metrics for operations performed within the previous iteration of the migration:

10 clients created, all with their secrets updated; 5 of them were DCR clients
3 clients deleted within the same iteration

2026-09-29 06:51:11 [INFO] Iteration summary [Another Service (309958490091)]: clients created 10 (skipped=0 failed=0) secrets updated 10 (attempted=10 skipped=0 failed=0) dcr clients configured 5 (attempted=5 skipped=0 failed=0) clients removed 3 (attempted=3 skipped=0 failed=0) errors 0

Token Migration (Dedicated and Self-Managed)

Tokens are migrated separately by the Token Migrator. See Migrating Tokens to Authlete 3.0.

Migrating using the Authlete Management Console (Shared environment only)

In the case of migrating an account residing on one of the Authlete Shared environments, the migration will be done through the Authlete Management Console UI. The general upgrade path is as follows:

Log in to the Authlete Management Console of the new Authlete 3.0 environment
Create and configure the amount of Organization(s) that are needed for the migration
Service and Client Migration (Refer to below section) - Using the Import/Migrate feature, import the appropriate service(s) and client(s) into this organization
Token Migration - Optional, if existing tokens need to be available in the new 3.0 environment
Update OAuth Server / Applications

If you use the zero downtime (parallel cutover) approach, deploy the changes to your authorization server before step 3.

The Token Migrator only has read access to the source DB and is therefore unable to alter data of any kind.

Service & Client Migration

Log into the Authlete Management Console, and go to Organization Settings > Basic Settings > Import/Migrate
Log into the Authlete 2.x Service Owner Console, and copy/paste the Service Owner API Key and API Secret from your account (can be found in the Your Account page)

Your Account page in the Authlete 2.x Service Owner Console

Enter the Authlete API URL for your cluster

Enter one of the corresponding URLs below:
- US : https://api.authlete.com
- Japan : https://tokyo.authlete.com
- Brazil : https://latam.authlete.com

Click Continue

Service migration form

The API should return a list of services that are attached to that account
Tick the checkbox next to the services you would like to migrate
If you plan to use the Token Migrator, tick the Synchronize Client Tokens and Migrate Client Secrets checkboxes. This will ensure clients belonging to the service are detected, and their tokens and/or secrets are migrated to the 3.0 environment. This property can also be updated individually per client after the import, under Client Settings > Basic Settings > Advanced > Migration Settings.
Click on the Select cluster dropdown to choose a cluster under which to migrate services

Service selection

Click Continue
Click Import on the confirmation screen
The services (and attached clients) should now appear inside the Authlete Management Console navigation

Migration confirmation

Token Migration (Shared)

Tokens are migrated separately by the Token Migrator. See Migrating Tokens to Authlete 3.0.

Terraform

Self-Managed Deployment

Observability

Performance

Migration from Existing System

Networking

Integration with API Gateways

Operational Policies

Access Control

Migrating Settings to Authlete 3.0

Migrating using the Configuration Migrator (Dedicated and Self-Managed)

Downloading the Configuration Migrator

1. Create an Organization

2. Request Access

3. Generate a Registry Access Token

4. Authenticate and Pull Images

Preparation

Prerequisites for Migrating Dynamically Registered Clients

How the Configuration Migrator Works

Migration Settings

Available Settings

Required Settings

Optional Settings

Migration Steps

1. Confirm Environments Are Set Up and Running

2. Set Up the Configuration Migrator

3. Running in Dry Run Mode

4. Running the Migration

5. Checking the Result

Token Migration (Dedicated and Self-Managed)

Migrating using the Authlete Management Console (Shared environment only)

Service & Client Migration

Token Migration (Shared)

​Migrating using the Configuration Migrator (Dedicated and Self-Managed)

​Downloading the Configuration Migrator

​1. Create an Organization

​2. Request Access

​3. Generate a Registry Access Token

​4. Authenticate and Pull Images

​Preparation

​Prerequisites for Migrating Dynamically Registered Clients

​How the Configuration Migrator Works

​Migration Settings

​Available Settings

​Required Settings

​Optional Settings

​Migration Steps

​1. Confirm Environments Are Set Up and Running

​2. Set Up the Configuration Migrator

​3. Running in Dry Run Mode

​4. Running the Migration

​5. Checking the Result

​Token Migration (Dedicated and Self-Managed)

​Migrating using the Authlete Management Console (Shared environment only)

​Service & Client Migration

​Token Migration (Shared)

Migrating using the Configuration Migrator (Dedicated and Self-Managed)

Downloading the Configuration Migrator

1. Create an Organization

2. Request Access

3. Generate a Registry Access Token

4. Authenticate and Pull Images

Preparation

Prerequisites for Migrating Dynamically Registered Clients

How the Configuration Migrator Works

Migration Settings

Available Settings

Required Settings

Optional Settings

Migration Steps

1. Confirm Environments Are Set Up and Running

2. Set Up the Configuration Migrator

3. Running in Dry Run Mode

4. Running the Migration

5. Checking the Result

Token Migration (Dedicated and Self-Managed)

Migrating using the Authlete Management Console (Shared environment only)

Service & Client Migration

Token Migration (Shared)