Go to developer

Going live with KEYRA

Your integration works locally. Use this guide to configure production credentials, URLs, security, and failure handling — then go live.

On this page

Path to production

  1. Complete full flows in development/sandbox (enroll → challenge → consume, or OAuth → validate → session).
  2. Create/configure production credentials in the Developer Portal.
  3. Update server environment variables (never ship secrets in frontend bundles).
  4. Register production callback / redirect URIs (exact match for OAuth).
  5. Run production verification tests against real domains over HTTPS.
  6. Go live — there is no separate KEYRA “activation ceremony” beyond project credentials and configuration.

Environment differences

ConcernDevelopment / testProduction
Credentialscp_test_ / sk_test_cp_prod_ / sk_prod_
API hosthttps://auth.keyra.ie
OAuth callbackRegistered localhost URI (exact)HTTPS production URI (exact)
Partner returnUrlOrigin must match project callbackSame rule — production origin
LoggingMore verbose OK in private envsNever log secrets or tokens

Production checklist

Credentials

  • Production credentials configuredcp_prod_ / sk_prod_ on the server
  • No secrets in frontendPublishable client id only in the browser
  • Secrets from secure environment / secret manager
  • No test credentials remaining in production config

URLs

  • Production callback / redirect URI registered
  • HTTPS in production
  • Exact redirect_uri string matches configuration
  • No localhost URLs left in production OAuth config

Authentication

  • Backend validation enabledPOST /verify/validate for OAuth
  • Application session created server-side after KEYRA success
  • Failure paths handled (deny, timeout, invalid_grant, already_used)

Partner 2FA

  • Enrollment flow tested end-to-end
  • Challenge flow tested; expiry handled in UX
  • One-shot verificationToken capture understoodPrefer waitForChallengeApproval()
  • Recovery considered for your product
  • Disable behavior understoodDoes not cancel in-flight challenges

OAuth

  • PKCE enabled (S256)
  • State validated (Web SDK / your redirect handler)
  • Popup/redirect failure handled
  • Verification token validated server-side (single-use)

Reliability

  • Timeouts configured thoughtfully
  • Retry policy respects one-shot tokens / codes
  • Polling honors pollAfterMs — no tight loops
  • Network / 429 handling with backoff

Credential management

  • Load secrets from environment variables or a secret manager — not source control.
  • Browser-safe: publishable client id only.
  • Server-only: client secret / Partner secret Bearer material.
  • If a secret is exposed: rotate in the Developer Portal and redeploy. Docs do not claim an automated rotation API beyond portal-managed credentials.
Server environment (example)Bash
KEYRA_CLIENT_ID=cp_prod_…
KEYRA_CLIENT_SECRET=sk_prod_…
# Never NEXT_PUBLIC_ the secret

Logging guidance

Safe / usefulNever log
challengeId, enrollmentId, HTTP status, KEYRA error code, state transitions, timestamps, auth_request_id when presentclient secret, verificationToken / access_token, authorization code, recovery codes, session cookies, raw PII beyond what your compliance policy allows

Timeouts & retries

  • Safe to retry with backoff: transient network failures, rate_limited (429), server_unavailable (503).
  • Do not blindly retry: token exchange with the same authorization code; consumeChallenge / /verify/validate with the same token; disable / recovery without understanding side effects.
  • SDK wait helpers time out (challenge wait ~120s, enrollment wait ~600s in TypeScript defaults; Web OAuth default timeoutMs 120000). After timeout, start a new flow.

Polling best practices

  • Prefer SDK helpers: waitForEnrollment, waitForChallengeApproval.
  • Honor pollAfterMs from KEYRA responses.
  • Stop on terminal states (approved/denied/expired/cancelled/failed).
  • Capture verificationToken on the first approved poll — it is one-shot.
  • See verification token troubleshooting.

Security checklist

  • Secret credentials only on the server
  • HTTPS in production
  • PKCE (S256) for OAuth
  • Validate OAuth state
  • Validate KEYRA result server-side before creating a session
  • Use secure application session cookies (HttpOnly; Secure in production)
  • Never log verification tokens or secrets
  • Protect recovery codes
  • Handle token replay / already_consumed / already_used errors

Common mistakes

  • Using client secret in React — troubleshoot
  • Treating browser onSuccess as an authenticated session — troubleshoot
  • Generating a new challenge during completion instead of consume
  • Polling again after receiving a one-shot verificationToken
  • Passing enrollment/challenge URL directly to an <img> without encoding needs
  • Using Web SDK on the server, or server SDK in the browser
  • Regenerating PKCE verifier before token exchange
  • Callback URL that does not exactly match OAuth configuration
  • Assuming disable2FA cancels in-flight challenges
  • Assuming TypeScript disable2FA({ reason }) persists reason server-side

Monitoring

KEYRA docs do not claim a partner-facing monitoring, alerting, webhook, or analytics product for these flows unless separately productized. Monitor your own integration: validation success rate, challenge completion, error codes, and latency.

Still stuck?

Collect SDK + version, endpoint, HTTP status, KEYRA error code, timestamp, and resource ids. Never send secrets or tokens. Start with Troubleshooting and Error reference.