Build on Xirag Gate

How a Gate sign-in actually flows

Gate is a broker with three services your app talks to, in order — plus your own backend at the end of the chain. No step here holds your customer's user directory, and nothing but the last hop ever touches your infrastructure.

Quickstart

You don't provision your own tenant by hand — a client_app_id and registered redirect_uri come from your Xirag Gate account team, the same way an OAuth app registration would from any provider. From there, five steps get you to a signed-in session.

1. Get your client_app_id

   Tell your account team your platform (web, Windows, Linux, or Android) and your redirect_uri — for web that's your BFF's callback route; for desktop and Android it's a loopback URL or a custom URI scheme. See platform guides below.

2. Install your platform's SDK

   Web is @xirag/gate-web (npm), Windows and Linux share gate-desktop (Go module), Android's GateClient.kt is a reference implementation you copy into your project — there's no packaged Android artifact yet.

3. Call discover(domain)

   Resolves the user's organization to a sign-in URL. Always returns a result, even for domains Gate doesn't recognize yet — check status before proceeding.

4. Send the browser to authorize_url

   Your SDK appends PKCE and state parameters for you. The user authenticates with their own organization's identity provider — Gate never sees their password.

5. Exchange the code, establish your session

   exchangeCode() gets you a DPoP-bound handover token; establishSession() presents it to your own backend, which validates it and starts whatever session model your app already uses.

The authentication model, briefly

Three ideas do all the work. Understanding them makes every SDK call below make sense instead of feeling like magic.

The token your app receives — the handover token — isn't a plain JWT you can inspect. It's a signed assertion nested inside an encrypted envelope, sealed specifically to your registered backend's public key (ECDH-ES + A256GCM around an EdDSA-signed JWS). Nothing between Discovery and your backend — including Gate's own broker — can read what's inside it. Your backend decrypts, verifies, and is the only party that ever sees the claims.

Platform guides

Every SDK implements the same four calls — configure → discover → authorize → exchange/establish — shaped to fit how each platform actually works.

import { GateClient } from "@xirag/gate-web";

// Once, at server startup — generates and holds this process's DPoP key.
const client = await GateClient.configure({
  clientAppId: "<your registered client_app_id>",
  hrdBaseUrl: "https://hrd.your-domain.example",
  tokenBaseUrl: "https://token.your-domain.example",
  redirectUri: "https://yourapp.example/callback",
});

app.post("/login", async (req, res) => {
  const domain = req.body.email.split("@")[1];
  const discovered = await client.discover(domain, deviceId, req.get("user-agent"));
  const pending = await client.beginAuthorize(discovered);
  // Persist `pending`, keyed by pending.state, in a real server-side
  // session store with a TTL — not an in-memory Map with no expiry.
  res.redirect(pending.redirectTo);
});

app.get("/callback", async (req, res) => {
  const pending = lookupByState(req.query.state);
  const tokenResult = await client.exchangeCode(req.query.code, pending, req.get("user-agent"));
  const session = await client.establishSession(tokenResult, req.get("user-agent"));
  // session.name, session.email, session.tenantId — set your own cookie here.
});

import gatedesktop "github.com/xirag/gate/sdk/gate-desktop"

client, err := gatedesktop.Configure(gatedesktop.Config{
    ClientAppID:  "<your registered client_app_id>",
    HRDBaseURL:   "https://hrd.your-domain.example",
    TokenBaseURL: "https://token.your-domain.example",
    KeyPath:      keyPath, // persisted across launches, see below
    UserAgent:    "YourApp/1.0 (windows; amd64)",
})

discovered, err := client.Discover(ctx, domain)

// Opens the default browser via the OS shell, listens on a loopback
// port Windows/the OS assigns automatically, blocks until the redirect
// lands (or AuthTimeout, default 5 minutes), then exchanges the code.
tok, err := client.Authenticate(ctx, discovered)

session, err := client.EstablishSession(ctx, tok)

import gatedesktop "github.com/xirag/gate/sdk/gate-desktop"

client, err := gatedesktop.Configure(gatedesktop.Config{
    ClientAppID:  "<your registered client_app_id>",
    HRDBaseURL:   "https://hrd.your-domain.example",
    TokenBaseURL: "https://token.your-domain.example",
    KeyPath:      keyPath,
    UserAgent:    "YourApp/1.0 (linux; amd64)",
})

discovered, err := client.Discover(ctx, domain)
tok, err := client.Authenticate(ctx, discovered) // xdg-open under the hood
session, err := client.EstablishSession(ctx, tok)

// DeviceKey.kt — AndroidKeyStore EC P-256, StrongBox-preferred with a
// real fallback (confirmed correct on emulators, which have no StrongBox):
object DeviceKey {
    fun getOrCreate(): KeyStore.PrivateKeyEntry { /* setIsStrongBoxBacked(true),
        catch StrongBoxUnavailableException, fall back to hardware Keystore */ }
}

// GateClient.kt — direct to HRD/Broker/Token, no BFF:
class GateClient(clientAppId: String, hrdBaseUrl: String, tokenBaseUrl: String) {
    private val entry = DeviceKey.getOrCreate()
    val deviceId: String = Dpop.thumbprint(entry.certificate.publicKey as ECPublicKey)

    fun discover(domain: String): DiscoverResult { /* POST /v2/hrd/resolve, DPoP-signed */ }
    fun exchangeCode(code: String, verifier: String): TokenResult { /* POST /v2/token */ }
    fun establishSession(tok: TokenResult): SessionResult { /* POST <backend>/auth/gate/session */ }
}

// The authorize leg opens a Chrome Custom Tab (androidx.browser) — never
// an embedded WebView — and returns via a custom scheme deep link:
// xiraggate://callback, handled by a dedicated Theme.NoDisplay activity.

API reference & Swagger

The full contract — five operations across three services — as an OpenAPI 3.1 document. Browse it below, or pull it into your own tooling (codegen, Postman, Insomnia — anything that reads OpenAPI).

Errors

Every service returns the same envelope on failure — trace_id is what to hand support if you need help with a specific request.

{
  "code": "IDP_ASSERTION_INVALID",
  "message": "The identity provider's response failed verification.",
  "trace_id": "9f2c1e7a-...",
  "help_url": "https://docs.gate.xirag.com/errors/idp_assertion_invalid"
}

Rate limits & CORS

Common integration mistakes

Not hypothetical — every one below was a real bug hit while building and testing these exact SDKs.