rpId — Tenant Identification

What is rpId?

The rpId (Relying Party Identifier) is a domain string that serves two purposes:

1. Tenant isolation — The IBEx API uses the rpId to scope users, wallets, and credentials to your application. Each rpId is an isolated namespace.
2. WebAuthn security — The browser enforces that the rpId is a registrable domain suffix of the page origin. This prevents cross-domain credential theft.

How to pass your rpId

Every request to the IBEx API must include your registered rpId. Pass it via one of:

Priority: explicit rpId param > Origin header > Referer header.

If the rpId is missing or not registered, auth endpoints return:

{ "message": "Unknown domain/rpId" }

Your rpId must be registered with IBEx before use. Contact your IBEx account manager or contact@ibex.fi.

WebAuthn rpId constraint

The WebAuthn specification requires that the rpId must be a registrable domain suffix of the current page origin:

Using your apex domain (e.g., mycompany.com) as rpId is recommended — it works across all your subdomains.

Local development (localhost)

On development environments, localhost, 127.0.0.1, and [::1] are automatically recognized and mapped to a pre-configured localhost domain with a generous daily quota.

This means you can develop and test directly from http://localhost:3000 (or any port) without any DNS configuration:

GET https://api-host/v1.2/auth/sign-up?rpId=localhost
→ Returns WebAuthn options with rpId: "localhost"
→ Browser on http://localhost:3000 accepts rpId "localhost" ✓

Browsers treat localhost as a secure context, so WebAuthn works over plain HTTP on localhost — no TLS certificate needed.

Important: Passkeys created with rpId: "localhost" only work on localhost. They will not be available when your app moves to production with a different rpId. This is expected — localhost is for development and testing only.

Production setup

For production, register your domain with IBEx and pass it as the rpId. Two common patterns:

Pattern 1: Direct API calls (recommended for SPAs)

Your frontend calls the IBEx API directly. The browser sends the Origin header automatically.

Frontend: https://app.mycompany.com
    ↓ fetch("https://passkeys.ibex.fi/v1.2/auth/sign-up")
    → Origin: https://app.mycompany.com
    → rpId resolved: mycompany.com (registered in IBEx)
    → WebAuthn rpId: mycompany.com ✓ (suffix of app.mycompany.com)

For this to work, your WebAuthn ceremony must run on a page whose origin is under your registered rpId domain.

Pattern 2: Backend proxy

Your backend proxies requests to the IBEx API. Pass the rpId explicitly:

Backend: POST https://passkeys.ibex.fi/v1.2/auth/sign-up
    Headers: X-RpId: mycompany.com

Common errors

Summary

• Register your domain with IBEx as your rpId
• Pass it via ?rpId=, X-RpId header, or let the browser Origin header resolve it
• For local development, localhost works automatically on development environments
• Use your apex domain as rpId for maximum flexibility across subdomains