Connect to a custom environment

Connect the io.sign mobile app to a custom environment before signing in when your organisation runs io.sign in customer cloud, on-premise, or an air-gapped network.

Before you start

Obtain the configuration-endpoint server details from your io.sign administrator. Do not derive or guess the endpoint from another service URL.

Your device must be able to reach the configuration endpoint. For a private or air-gapped environment, first connect the device to the required internal network or approved VPN and install any organisation-managed certificate trust required by that environment.

Configure the environment

1. Open the io.sign app to its landing page.
2. Select Add custom environment.
3. Under Add from URL, paste the full configuration URL supplied by your administrator, including /v2/app/config when using the io.sign endpoint.
4. Select Add environment, then select the saved environment from the environment list. Check the displayed label and API hostname against the administrator's details.
5. Select Switch to confirm the environment change. The app applies the selected configuration and restarts.

After restart, sign in with the account issued for that environment. Accounts, registered signers, and vaults belong to a specific environment; credentials from the default environment may not work in a customer-operated environment.

Adding an environment saves it to the list; selecting it switches the app to it. If Add custom environment is unavailable, ask your administrator for the compatible app build for your deployment.

Administrator setup

Configure public app configuration on the backend. The response needs a stable envKey, a label, the reachable ioSignApiUrl, and either Clerk publishable-key settings or OIDC public-client settings. Treasury is optional.

For example, distribute https://sign.example.com/v2/app/config, not just https://sign.example.com. Public hosts require HTTPS. A local evaluation can use HTTP on a private address supported by the app, but a phone cannot use your computer's localhost address. The localhost-only backend quick start needs a separately secured, device-reachable deployment before mobile use.

Verify the connection

After signing in:

1. Confirm that the expected organisation is shown.
2. Confirm that the device can be registered as a signer, or that its existing signer registration appears.
3. Ask your administrator to confirm that the device is connected to the intended io.sign environment before assigning it to a production vault.

Troubleshooting

• The app cannot retrieve the configuration: confirm the server details, network or VPN connection, DNS resolution, and TLS certificate trust with your administrator.
• The app restarts but sign-in fails: make sure you are using an account issued for the custom environment.
• The expected organisation or vaults are missing: stop and verify the configuration endpoint with your administrator. Do not register or approve requests until the target environment is confirmed.

Security guidance

• Accept configuration details only from an authorised administrator.
• Do not bypass certificate warnings or install an unverified certificate profile.
• Treat a change of environment as security-sensitive: it changes the servers that provide identity, requests, and signer connectivity to the app.

Screenshots can supplement this flow, but the written endpoint details supplied by your administrator remain authoritative.