Developer API Keys

API keys authorize every request to a Seev API product. Keys are scoped to one product and one environment, so a sandbox Checkout API key cannot sign a production request and cannot be used against the Exchange Widget API. This page is the reference for authentication; the pages for Checkout and Webhooks assume you already hold a key.

Before you can create a key, open the Developer Dashboard and accept the developer terms for the active organization. Accepting the terms enables developer access, and it does not create a key for you.

Authenticate a request

Send the key from your server in either the Authorization header or the X-API-Key header. Seev reads X-API-Key first and falls back to a Bearer token in Authorization, so sending both is redundant.

curl -X POST "https://api.seevplus.com/api/v1/developer/payments" \
  -H "Authorization: Bearer $SEEV_CHECKOUT_API_KEY" \
  -H "Idempotency-Key: order_123_attempt_1" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "checkout",
    "recipient": { "name": "Kwame Asante", "email": "kwame@example.com" },
    "amount": 10000,
    "currency": "GHS",
    "redirect_url": "https://yourapp.com/payment/callback"
  }'

amount is expressed in the currency's smallest unit, so 10000 means GHS 100.00. The same convention applies to item prices. See Checkout API for the full request body.

Choose a product for the key

Each Seev API product is backed by a separate service, so you pick the product at creation time and the key is valid only for that service.

You can hold several keys for the same product, which is how you give each deployed application its own credential and rotate one without disturbing the others.

Generate a key

1. Open Seev API -> API Keys and confirm the environment selector shows the environment you want.
2. Click Generate Key.
3. Select the product.
4. Enter a name that identifies where the key will run, such as Tally Mobile App or Merchant Portal.
5. Optionally enable IP whitelisting and enter the public IP addresses your server sends from.
6. Click Create Key.

A new key returns a public key and a secret key. The full secret is shown once, on the confirmation screen, and the API Keys table afterwards shows only the public key and a masked prefix of the secret. Copy the secret into a secrets manager before you close that screen. If you lose it, Seev cannot show it again, and your only path back to a working credential is to rotate the key and update your application with the new secret.

Store the secret in an environment variable or a secrets manager such as AWS Secrets Manager, HashiCorp Vault, Doppler, or your host's own secret store, and load it at runtime.

# .env (local development only, never committed)
SEEV_CHECKOUT_API_KEY=your_sandbox_or_production_key

# .env.example (safe to commit)
SEEV_CHECKOUT_API_KEY=

Restrict a key by IP address

IP whitelisting compares the public IP that the request arrives from against the list stored on the key, and rejects anything else. The comparison is an exact string match against the first address in the forwarded chain, so ranges and CIDR blocks are not accepted.

Enable it for server-side integrations with stable outbound addresses. Leave it off where your egress IP rotates, unless you can update the list before it changes, because a stale list fails every request on that key.

A blocked request returns 403:

{
  "error": "request IP is not allowed for this API key",
  "message": "request IP is not allowed for this API key"
}

Add the current egress address to the key's whitelist, or disable whitelisting on the key, then retry.

Move a key from sandbox to production

Keys belong to one environment and cannot cross over.

Switching the environment selector in the dashboard changes which keys the API Keys tab lists. Going live means generating a separate production key and deploying it, not promoting the sandbox key.

Rotate a key

Rotate when a secret may have leaked, when someone with access leaves, or on the schedule your credential policy sets. Rotation revokes the previous key record and issues a replacement whose secret is shown once, the same as at creation.

Rotation is immediate, so sequence the rollout to avoid a window where the deployed application holds a revoked secret:

1. Rotate the key in the dashboard and copy the new secret.
2. Write the new secret into your application's secret store.
3. Deploy, then confirm a sandbox request or a low-value controlled production request succeeds.
4. Remove the old value from environment files, CI variables, and local copies.

Delete a key

Deleting removes the key from its environment and stops every request that presents it. Confirm no running deployment depends on it first. Giving each application its own named key is what makes deletion safe to do without an outage.

Fix a rejected request

Seev returns errors as a JSON object carrying the same string in both fields:

{
  "error": "invalid API key; existing keys must be rotated once before using this endpoint",
  "message": "invalid API key; existing keys must be rotated once before using this endpoint"
}

Deleted and rotated-away keys behave like unknown keys, so they return the invalid API key message rather than a distinct revoked-key error.

Check before you go live

• Generate a fresh production key instead of reusing sandbox configuration.
• Give every deployed application its own named key.
• Add IP restrictions only where the egress addresses are stable.
• Verify payments on your server before fulfilment. A browser redirect is not proof of payment.
• Configure a signed webhook endpoint for asynchronous updates.
• Write down the rotation procedure before you need it.

Related docs

• Checkout API
• Developer Webhooks
• Developer Transactions
• Idempotency
• Errors and codes