Developer Q&A: Best Practices for Authenticating Against the SimpleVisa API

Why authentication matters

When you connect your product to SimpleVisa, you gain the ability to quote, create and track visa applications in real time. That power also exposes sensitive traveler data and—if mishandled—could lead to failed applications or even border-crossing issues for your customers. Robust authentication is therefore your first line of defence against:

• data leaks and account takeover
• fraudulent visa submissions that inflate your ancillary bill
• noisy 4XX/5XX errors that ruin the checkout experience

In this Q&A-style guide we’ll cover the questions we hear most often from engineering teams during implementation and walk through best practices that will keep your integration secure, scalable and compliant in 2025 and beyond.

Looking for an architectural overview first? Check our primer How eVisa APIs work — Step by Step.

---

1. Which auth scheme does the SimpleVisa API use?

SimpleVisa supports a two-tier model:

1. Server-to-server REST requests are authenticated with long-lived API keys sent in the Authorization header. Keys are scoped to an environment (sandbox / production) and to a capability (read-only, read-write, admin).
2. End-user hand-offs—for example when you redirect passengers to the white-label Application Flow—rely on signed JWT session tokens that expire after 30 minutes.

Most partners only need the first tier; the second is generated automatically by the SimpleVisa SDK during white-label redirects.

2. How do I create and rotate an API key?

POST /v1/partners/{partnerId}/apikeys
Content-Type: application/json
Authorization: Bearer <your-admin-key>

{
  "label": "flight-checkout-prod",
  "scopes": ["visa.read", "visa.write"],
  "expiresInDays": 90
}

The response contains:

{
  "id": "key_live_k9Nq...",
  "secret": "sk_live_D4ab...",
  "createdAt": "2025-07-19T18:20:11Z",
  "expiresAt": "2025-10-17T18:20:11Z"
}

Best practices

• Rotate every 90 days. Use the expiresInDays parameter so keys self-destruct.
• Store secrets in a vault (AWS Secrets Manager, HashiCorp Vault, Azure Key Vault…). Never commit them to Git.
• Tag keys with a label that matches the micro-service ("checkout", "backoffice"…). This speeds up incident response.

3. What header format should my client send?

Authorization: SimpleVisa key_live_k9Nq...:sk_live_D4ab...

The first token is the public key (identifier); the second is the secret. Colon-separated formatting allows our edge proxy to reject malformed requests before they hit the core.

⚠️ Avoid BEARER tokens. They are accepted for backward compatibility but will be deprecated Q1 2026.

4. Should we pin SimpleVisa’s TLS certificate?

We already leverage TLS 1.3, HSTS and a dedicated certificate chain. Certificate pinning is optional and not recommended for public-facing mobile apps, because forced updates can break production traffic when certs rotate. If you run an internal B2B service in a controlled environment, DNS CNAME + SPKI pinning is acceptable.

5. How do I handle sandbox vs. production?

Environment	Base URL	Test data
Sandbox	https://sandbox.api.simplevisa.com	Uses staging databases; no real immigration checks
Production	https://api.simplevisa.com	Live applications submitted to border authorities

Create distinct API keys for each. Never reuse credentials across environments.

Tip: inject the base URL and key at deploy time via environment variables such as SV_API_URL and SV_API_KEY.

6. Rate limits & 429 errors

SimpleVisa enforces quota buckets per key—not per partner—so remember to split high-throughput workloads into dedicated keys.

Default limits (subject to contract):

• 1 000 requests / minute
• 10 requests / second burst

A Retry-After header is returned with 429 Too Many Requests. Back off exponentially and retry.

7. How can I verify the integrity of webhooks?

Every webhook request sent by SimpleVisa includes two headers:

SV-Signature: t=1628203154,v1=d3b3...f02
SV-Key-Id: key_live_k9Nq...

1. Concatenate the timestamp (t) with the raw body.
2. Compute an HMAC-SHA256 hash using your webhook secret.
3. Compare the hash with the v1 value.

Rotate the webhook secret just like API keys. A replay attack window of five minutes is applied on our side; we reject older timestamps.

8. What if a key leaks?

1. Revoke immediately via the Partner Dashboard → Security → API Keys.
2. Create a replacement key and redeploy.
3. Check your audit logs for suspicious calls (Dashboard → Logs). You can also stream logs to your SIEM via the /v1/logs/subscribe endpoint.

9. Does SimpleVisa support OAuth 2.0?

For simplicity and to avoid additional round trips, the public API uses static keys. An OAuth 2.0 client-credentials flow is available on request for enterprise partners who must comply with PSD2 or similar regulations. Contact your account manager or request a demo to enable it.

10. How do I test error scenarios?

In sandbox you can trigger deterministic errors with magic values:

Field	Value	Simulated response
passportNumber	TEST-401	401 Unauthorized (invalid key)
passportNumber	TEST-429	429 Too Many Requests
passportNumber	TEST-500	500 Internal Server Error

This trick lets you verify your retry logic without manipulating real keys.

11. Common pitfalls at a glance

• Hard-coding keys in frontend code. Browser dev-tools will expose them. Use the white-label hosted flow instead.
• Using the wrong Content-Type. Only application/json and multipart/form-data are accepted.
• Clock skew. Ensure your servers sync with NTP; a skew >5 minutes will invalidate JWT session tokens.
• Forgetting to URL-encode path parameters—especially passport numbers with special characters.

12. Staying compliant

The SimpleVisa platform is ISO 27001-certified and aligns with GDPR. Under the joint controller model, you must:

• obtain traveler consent before sending PII;
• purge or anonymise data that you store longer than the allowed retention period;
• report breaches within 72 hours.

See the full Data Processing Addendum in the Partner Dashboard → Legal.

TL;DR checklist

• Generate separate API keys for sandbox and prod
• Store secrets in a vault; never in code
• Rotate keys every 90 days (set expiresInDays)
• Monitor usage; handle 429 with exponential back-off
• Verify SV-Signature on every webhook
• Keep servers’ clocks in sync (≤ 5 min skew)
• Use magic passport numbers to test failure paths

By following these best practices you’ll keep your integration lean, secure and future-proof, ensuring travelers enjoy the “travel made simple” promise of SimpleVisa without ever noticing the complex visa machinery running behind the scenes.