Skip to content

Upgrade from the Shared Token

Earlier releases authorized REST API calls with one shared token in server\config\apitoken.json; at upgrade, MetaMiner turns that token into the API client api so existing scripts keep working.

What happens at upgrade

You do not have to do anything. When the upgraded MetaMiner Server (MMS) starts, it:

  1. Reads server\config\apitoken.json, about 20 seconds after start.
  2. Creates the admin client api from the token's hash: full access, no expiry, Created by "imported from config/apitoken.json on ".
  3. Renames the file to apitoken.json.imported-<yyyyMMdd>-<HHmmss>. You can delete the renamed file.

Scripts keep sending the same token and keep working, including calls to the deprecated POST /apitoken/rotate; move those to its replacement, POST /fss/v1/clients/me/rotate (see Rotate, Expire, Revoke).

Situation Result
The Flow Scheduler is switched on but not answering yet The import retries every minute until it answers, then completes
apitoken.json holds no usable hash Nothing is imported, a warning is logged and the file is renamed. Create a client for each script.
The same token was revoked earlier as an API client It is not brought back
api already exists with a different token The token is imported as api-<host> (the short host name in lower case)

High-availability pairs

Each node imports its own apitoken.json, the standby included. The clients are shared through the Flow Scheduler database, so there is no token file to copy between nodes any more.

Tokens on the two nodes Result
The same token on both One client, api
Different tokens api and api-<host>. Both tokens now work on both nodes.

What was removed

Removed Use instead
The Renew... dialog for the shared token Manage API Clients... in MetaMiner Administrator (MMA)
Creating the first token over HTTP (bootstrap) Create the first client in MMA, which needs no token
JVM arguments mms.api.token.remote.bootstrap and mms.api.token.bootstrap.ips Nothing; remove them from your service configuration

The modes were renamed: Token is now API clients and None is now Local only. See Authorization Modes.

Before you begin

  • The MMS is upgraded and running.
  • You know which scripts and integrations use the shared token.
  • You can run MMA on the MMS machine (the leader, in a high-availability pair).

Steps

The import keeps every script working, but one shared token cannot tell callers apart or stop one without the others. Move each caller to its own client:

  1. In MMA, open Manage API Clients... and check that api (and api-<host> in a pair with different tokens) is listed as Active.
  2. Create one client per script or integration (see Manage API Clients).
  3. Give each script its own token and run it once.
  4. In the API Clients window, check Last used of api. When no script uses it any more, select it and click Revoke....

The audit trail then names each real caller, and one caller can be stopped without affecting the others.

Verify

  • api shows Status Revoked, and each new client shows Active with a recent Last used.
  • GET /fss/v1/info answers 200 with each script's new token and 401 with the old shared token.

Troubleshooting

401 on every call after the upgrade

The old apitoken.json held no usable hash, so nothing was imported. Look for the import warning in the MMS log, then create a client and give the script its token.

A remote script without a token now gets 401 API_AUTH_REQUIRED

The MMS runs in Local only, which accepts callers on the MMS machine only. Switch to API clients and give the script its own client.

Next steps