API Keys
Which key goes in your app and which stays on your server, how to rotate either one, and how to move an existing integration to a Client key.
Petify has two kinds of API key. Both are issued in the Petify Console and sent as the x-petnow-api-key header.
| Client key (app) | Secret key (server) | |
|---|---|---|
| Where it goes | The SDK inside your mobile app | Your server only |
| What it can call | Only what the device needs: SDK start-up and configuration, telemetry, POST /v2/capture-sessions, and image uploads | The whole Server API, including pet registration, identification, verification and lookup |
| SDK version | 1.5.0 or later | — |
| If it leaks | Someone can open capture sessions and upload images, within a rate limit. They cannot register, identify, verify or look up pets. | Someone can call every route on your account, including the ones you are billed for. Rotate it right away. |
A Client key that calls any other route gets 403 PETNOWB2B10014.
Where each key goes
Anything shipped inside an app binary can be read back out of it, so the app gets a Client key and the Secret key never leaves your server.
The recommended flow:
- Your server creates a capture session with the Secret key and sends the app only the session ID.
- The app captures with the SDK, initialised with the Client key, and uploads the images to that session with the same key (or hands them to your server to upload).
- Your server starts registration, identification or verification with the Secret key and receives the result.
If your app calls pet registration, identification or pet lookup directly today, move those calls to your server before you switch the app to a Client key. Otherwise they start failing with 403 the moment the app ships with a Client key.
A Client key needs SDK 1.5.0 or later. SDK 1.4.x calls a route that a Client key cannot use, so capture fails. Upgrade the SDK in the same app release that switches to the Client key.
Moving an existing integration to a Client key
Keys issued before Client keys were available (October 20, 2026) are Secret keys. If your app ships one of them, move the app to a Client key in this order. Each step keeps the previous key working, so nothing breaks in between.
- Find where the current key is used. Check your app and your server. In the Console, API Key Management shows each key's type and when it was last used.
- If your server uses the same key, give the server its own key first. Create a new Secret key, deploy it to every server instance, and confirm in the Console that the new key is being used.
- Create a Client key and release an app version that uses it, built with SDK 1.5.0 or later. Make sure the app no longer calls server-only routes itself (see Where each key goes).
- Wait for older app versions to drain. Users who have not updated still send the old key.
- Deactivate the old key. From then on it fails everywhere, including in any app version that still carries it.
You do not have to change upload code or capture flow for this. Only the key the app passes to the SDK changes.
Rotating keys
Several keys can be active at the same time (up to 10 per account, both types together), so you can always bring in the new key before retiring the old one.
- To deactivate a key, click the trash icon next to it in API Key Management and confirm Delete. It takes effect immediately and does not affect your other keys.
- A deactivated key cannot be reactivated. If you deactivate one by mistake, create a new one.
- There is no automatic rotation or expiry. Keys stay valid until you deactivate them.
- The Console's last-used time is updated at most once an hour. Before deactivating a key because it looks unused, wait until its last-used time is more than an hour old.
Client key (app)
- Create a new Client key.
- Ship a new app version with the new key.
- Let older app versions drain. The Console's last-used time on the old key tells you when it has gone quiet.
- Deactivate the old key.
Secret key (server)
- Create a new Secret key.
- Deploy it to every server, worker and job that calls the Server API. Store it in an environment variable or a secrets manager, never in source control.
- Confirm in the Console that the new key is in use and the old key's last-used time has stopped moving.
- Deactivate the old key.
If a key is exposed
- Secret key: rotate it now, following the steps above, and deactivate the exposed key as soon as your servers use the new one. Until then, anyone holding it can use your account.
- Client key: the damage is limited to opening capture sessions and uploading images. Rotate it with your next app release. Deactivate it sooner only if you see abuse, because that also stops every app version that still carries it.
If you are not sure which key was exposed or what it was used for, contact support@petnow.io.