Skip to main content
The application client secret is a short-lived, scoped credential the Embedded Banking API returns when an application is created. It authenticates follow-up calls against that single application from the browser — typically the white-label hosted app or an embedded widget — without exposing a backend bearer token to the client. For the broader picture of how an application moves through DRAFT, SUBMITTED, and COMPLETE, and which auth method is required at each step, see the application lifecycle guide.

​
When to use it

Use the client secret for any browser-side call against an existing application: updating applicant or business details, requesting verification codes, submitting verification, or submitting the application. Server-to-server calls keep using a bearer token from the client credentials flow — create the application and read the back-office side from your backend, and hand the client secret to the browser for everything else.

​
Token shape and header

The token is a high-entropy random string prefixed with cs_. Send it on the X-Client-Secret header. On per-application endpoints, requests that carry both X-Client-Secret and Authorization fail authentication; on collection-level endpoints (such as create and resume) X-Client-Secret is ignored and the request authenticates with the bearer token.
Example Request

​
Lifecycle

  1. Create. Your backend creates the application with a bearer token. The response includes clientSecret.
    Response (201 Created)
  2. Hand off. Your backend returns the secret to the browser once. Re-fetching the application via GET does not return it. The onboarding component is the exception: it is not a browser surface you control, so there is nothing to hand off to. It looks the application up on start-up and receives the same secret, which is what lets it carry on with an application your backend pre-populated. See Pre-populating an application.
  3. Use. The browser calls per-application endpoints (PATCH, verification, submission) with X-Client-Secret.
  4. Invalidate. Once the application reaches the COMPLETE state through submission, the client secret is invalidated and further calls with it fail authentication.

​
Expiry and refresh

Each secret is issued with a twenty-four hour expiry. The expiry extends only on calls made during the final six hours of the window; calls made earlier in the window do not extend it. A secret used at least once during each final six-hour window can stay valid indefinitely while the application remains in DRAFT. If the secret expires before the applicant completes the flow — for example, the applicant returns days later — use the resume flow to re-issue.

​
Scope and access

A client secret authenticates calls only against the single application it was issued for. The handler reads the application ID from the URL path; requests to any other application — or to non-application endpoints — fail authentication. GET and PATCH return the same body whichever credential you present. A client secret only ever reaches the application’s own creator or the applicant themselves, and both already hold every value in the response, so there is nothing to hold back from one and not the other. Social security numbers and tax IDs are the exception, and not because of the credential: no response model has a field for either. A read returns their last four digits and nothing more, so the applicant re-enters one to change it.

​
Endpoints that accept the client secret

Per-application paths under bank-account applications accept the client secret. Collection-level endpoints (create, resume) require a bearer token.

​
Resume flow

The resume endpoint re-issues a client secret for a DRAFT application when the prior one has expired. Your backend calls it with the applicant’s email; the new secret is delivered to the applicant by email — it is not returned in the API response.
Resume Request
Response (200 OK)
The response is always { "acknowledged": true } regardless of whether a matching DRAFT application exists for the supplied email — this prevents enumeration of applicant emails. If a match exists, the new secret is emailed to that address; if not, no email is sent. Resume requests are rate-limited per credential and email; excess calls also receive the acknowledgement response, not a 429.

​
Security notes

  • Treat the client secret like a bearer credential. It carries write access to the application until submission completes.
  • Hand the secret directly from the backend that created the application to the browser context that needs it. Do not log it, persist it in browser storage longer than necessary, or send it to third parties.
  • Do not combine X-Client-Secret with an Authorization header on the same per-application request.
  • Your backend sees the plaintext once, in the create response. It is not returned by GET, and resume delivers a replacement by email rather than in the HTTP response. The only other way it reaches anyone is the applicant’s own onboarding component fetching it for the application they started.