Skip to main content
Blueprints act on a third-party system on behalf of your end user, which means they need that user’s credentials. A credential session is a short-lived, Rubie-hosted form that collects those credentials, encrypts them, and vaults them — and hands you back nothing but an opaque id. The secrets never transit your infrastructure, so this flow keeps credential handling out of your compliance scope.

​
The shape of the flow

​
Choosing a strategy

Every session is created against an authentication strategy — a template that defines which fields the target system needs (username/password, bearer token, custom headers, TOTP, and so on). The strategy determines what the hosted form renders, so you don’t have to build or maintain a credential UI per integration. Strategy ids are provisioned by Rubie for your account. You’ll typically hold one per system you integrate with.

​
Creating a session

name is optional and is only a label for the vaulted credential in the Rubie dashboard. Something that identifies the end user or their account is a good choice — it’s what your team will see when debugging a run. return_url is optional. Its exact origin — scheme, host, and port — must be allowlisted for your account by Rubie. Paths and query strings can vary beneath that origin. For example, allowlisting https://app.example.com permits both https://app.example.com/settings and https://app.example.com/onboarding?step=connect, but not an http:// URL, a subdomain, or another port. Sessions expire after 7 days by default. hosted_url is populated only while status is pending; once a session is completed or expired it returns null, so the link cannot be reused.

​
Presenting the form

Open hosted_url in a new tab or an iframe. Either works — pick based on how much you want the flow to feel embedded. If users should choose from several Blueprints inside your product, use the Embedded Credential Capture widget instead. It provides a Blueprint picker, an origin-bound iframe, browser lifecycle events, and the selected Blueprint key on completion. The user may not finish in one sitting, and some strategies redirect out to the target system’s own login. Neither breaks anything: the session stays pending until it’s either submitted or expires, so you can re-open the same hosted_url as long as it’s still valid.

​
Returning to your app

After the user submits successfully, Rubie redirects them to your return_url with the session id appended:
Read session_id from the redirect and confirm the session through your backend with the authenticated API:
When status is completed, credential_id is populated. Store it against the user in your own database — Rubie does not own the mapping between your users and their credentials. That id is stable for the life of the credential. If the returned status is still non-terminal, poll every 2 seconds until it settles. This can happen as Rubie adds verification between form submission and completion. In the normal user-present flow, polling starts only after the redirect and lasts seconds — clients should not poll continuously for the session’s full seven-day lifetime. If you omit return_url, the hosted page shows a success message and tells the user they can close the tab. In that fallback flow, start polling when you open hosted_url and stop when the user closes the flow, the session reaches a terminal state, or your own short timeout expires. The session can still be checked later on an explicit user action.
Treat status as an open string set, not a fixed enum. Branch on the three values above and keep polling on anything you don’t recognise. Additional non-terminal statuses may appear between collection and completed — for example while Rubie verifies the credential against the target system. completed will always mean terminal and usable, so if (status === "completed") {save(credential_id)} is safe to write today and will stay correct.
Today, completed means the credentials were collected and vaulted — not that they were tested. Validity is checked on the first Blueprint run, so a typo’d password surfaces as a failed run rather than a failed connection. In-session verification is planned and will arrive as an extra non-terminal status, not as a change to the meaning of completed.

​
Reconnecting and revoking

Credentials go stale: users rotate passwords, revoke tokens, or churn. Two things to build for. Reconnect. There’s no “update credential” step in this flow. To replace a stale credential, create a new session, and swap the stored id once it completes. Revoke. When a user disconnects, delete the credential:
This is a hard delete — the vaulted secrets are destroyed and the id stops resolving. Drop your stored mapping at the same time.

​
Idempotency

Both POST /credential-sessions and DELETE /credentials/{id} accept an Idempotency-Key. Key it on the user or connection rather than the attempt, so a double-submitted “Connect” button replays the original session instead of creating a second one. See Idempotency.

​
Next