API Keys & Security

API keys are required to authorize the Geophrase Connect SDK within your application. In client mode, your key is present in client-side code and must be restricted to prevent unauthorized use. In server mode, your key never touches the frontend. Either way, the dashboard is where you manage keys, configure restrictions, and monitor usage.

Each API key has two parts: a public Key ID and a secret key. The SDK requires the Key ID (the keyId option) in every integration, while the secret key is only used to resolve addresses. The difference is explained in Key ID vs. secret key below.

Create an API Key

Go to API keys.
Click the + Create API Key button near the top right corner.
Enter an API Key name for your own reference, or accept the default name. If you create more than one API key, each name must be unique.
Add API Key restriction. If you are going to use the client mode, make sure appropriate client application is selected, e.g. Websites, Android apps or iOS apps. For server mode, make sure to select IP addresses and add your server's IP address or range.
Click Create & View.
Once the key is created, the dialog shows its Key ID in the title and the full secret key, which is displayed only once for security reasons. (The Key ID stays visible in the table afterwards; the secret key does not.)
Click the Copy icon next to the secret key and save it somewhere safe. You can create a new API key, but you can never retrieve this specific key again.
After you have copied and saved the key, click OK.

Key ID vs. secret key

Each API key is made up of two parts:

Key ID: A short, public identifier (for example, wij9si4o). It is the prefix of your full key and is always visible in the Key ID column of the API keys table. It is not a secret.
Secret key: The full key string (for example, wij9si4o-g8bi2v2NcTwswQc4Jd9D4XQbqghFN5SSyXFU663z1Eo). This is shown only once, at creation. It authorizes address resolution and must be protected.

How each is used in the SDK:

Value	SDK option	Required	Where it is used
Key ID	`keyId`	Always (both modes)	Sent to the widget to identify your account. Safe to expose in frontend code.
Secret key	`key` (client mode) / `X-API-Key` (server mode)	Client mode, or backend resolve	Resolves a Request ID into an address. Kept on the frontend only in client mode, otherwise backend-only.

In other words, every integration passes a keyId. Client-mode integrations additionally pass the secret key; server-mode integrations keep the secret key on the backend and never put it in the frontend. If you lose the secret key, create a new key and update your integration because it cannot be recovered.

Understanding Client-Side Exposure

In client mode, your API key will be visible in your application's compiled source code or network payloads. This is expected behavior. Frontend SDK keys rely on origin and platform restrictions rather than secrecy to remain secure.

For maximum security, use server mode. Your key never touches the frontend, and when combined with server IP whitelisting in the dashboard, only requests from your own backend can use it. See Client vs. Server Mode.

Security Best Practices

To ensure your integration remains secure and easy to manage, follow these standard practices:

1. Configure API Restrictions

To prevent malicious actors from copying your public key and embedding it on unauthorized platforms, restrict your keys to specific environments immediately after creation:

Web Applications: Restrict usage by whitelisting authorized origin URLs (e.g., https://checkout.yourdomain.com).
Mobile (iOS): Restrict usage to your specific Apple Bundle ID.
Mobile (Android): Restrict usage to your specific Android Package ID.

2. Platform Isolation

Do not share a single API key across multiple platforms. If you are deploying Geophrase on a web application, an iOS app, and an Android app, generate a distinct API key for each. This ensures that if one platform is compromised, the others remain unaffected.

3. Separate Environments

Never use your production API key in your local development or staging environments. Always create a dedicated key for testing (e.g., WebApp - Staging, WebApp - Production). This allows you to safely rotate or revoke a compromised development key without affecting your live checkout flow.

4. Rotate and Delete Keys

Periodically create new API keys, update your application to use them, and delete the old ones. Routinely audit your dashboard and delete any unneeded or inactive keys to keep your attack surface as small as possible.

5. Monitor Usage

Regularly monitor your API usage in the dashboard. Unexpected spikes in traffic or continuous validation failures can help alert you to unauthorized usage attempts or misconfigured restrictions.

Next step

Client vs. Server Mode