User Authentication

User authentication is done using The Bridge Auth Service that supports OAuth 2.0 / OpenID Connect. Tokens are issued as JWTs.

At a glance, the authentication process looks like this:

You initiate the login process by redirecting the user to the /authorize endpoint (or the simpler shorthand /login and /signup endpoints).
The user is pulled through an authentication process provided by The Bridge with cloud views.
Once the user is authenticated and has selected the tenant to access, the user is redirected back to your app with a code.
You make a call to the /token endpoint with this code to exchange it for access tokens and user profile information (OpenID).
You can verify that the tokens are valid and safe to trust by using the public keys available from the /.well-known endpoint.
You can refresh the tokens using the /token endpoint to obtain up-to-date access and profile information.

Authorize

Start the OAuth 2.0 user login flow by redirecting the user to the /authorize endpoint. The user will be able to choose a login method and after the authentication process get back to your app with an auth code that you can exchange for access and OpenID tokens.

HTTP Request

GET https://api.thebridge.dev/auth/authorize

Query Parameters

Parameter	Type	Required	Description
`client_id`	`string`	Required	Your app ID
`response_type`	`string`	Required	What kind of tokens will be generated. We support `code`
`redirect_uri`	`string`	Required	A target URI where the authenticated user will be redirected to together with tokens. Must be a valid URI in your App `redirectUris`
`scope`	`string`	Required	Any or all of: `openid`, `profile`, `email`, `address`, `phone`, `onboarding`, `tenant`
`state`	`string`	Optional	Used to resume a state in your app. The state will be available in the response code
`signup`	`boolean`	Optional	Set to true to initiate a signup instead of the default login flow
`signup_plan`	`string`	Optional	The key to an existing plan. Allows the signup to end with the new tenant subscribing to a specific plan
`force_federation`	`string`	Optional	Force a certain federated login flow: `ms-azure-ad`, `google`, or `saml`
`federation_connection`	`string`	Optional	Specify the federation connection ID to use with `force_federation`

You should redirect the user agent to this endpoint. This is not an API-to-API call. No x-api-key header is required; use your App ID in the client_id query parameter.

Request example

Build the authorize URL with your app ID, redirect URI, and scope, then open it in a browser to start the login flow.

# Build the URL (replace YOUR_APP_ID and open in browser)
# Use URL encoding for redirect_uri and scope if they contain special characters
curl -G 'https://api.thebridge.dev/auth/authorize' \
--data-urlencode 'client_id=YOUR_APP_ID' \
--data-urlencode 'response_type=code' \
--data-urlencode 'redirect_uri=http://localhost:8080/auth/oauth-callback' \
--data-urlencode 'scope=openid profile email tenant' \
--data-urlencode 'state=optional-state'
# Or open: https://api.thebridge.dev/auth/authorize?client_id=YOUR_APP_ID&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fauth%2Foauth-callback&scope=openid%20profile%20email%20tenant

Get Tokens

Get new tokens using an authorization code from a user who just completed authentication, or by using a refresh token that was issued to a logged-in user before.

HTTP Request

POST https://api.thebridge.dev/auth/token

Body Parameters

Parameter	Type	Required	Description
`client_id`	`string`	Required	Your app ID
`grant_type`	`string`	Required	`authorization_code` or `refresh_token`
`code`	`string`	Optional	Required for `authorization_code` grant. The code received from the authenticated user
`redirect_uri`	`string`	Optional	Required for `authorization_code` grant. Must be a valid URI in your App `redirectUris`
`refresh_token`	`string`	Optional	Required for `refresh_token` grant. The refresh token issued previously

Response `HTTP 200`

HTTP 200 — Returns access token, refresh token, and id_token.

Request example

# Exchange authorization code for tokens
curl --request POST 'https://api.thebridge.dev/auth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "client_id": "YOUR_APP_ID",
  "grant_type": "authorization_code",
  "code": "XXXX",
  "redirect_uri": "http://localhost:8080/auth/oauth-callback"
}'

# Refresh tokens
curl --request POST 'https://api.thebridge.dev/auth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
  "client_id": "YOUR_APP_ID",
  "grant_type": "refresh_token",
  "refresh_token": "XXXX"
}'

Response example:

{
    "access_token": "XXXX",
    "refresh_token": "XXXX",
    "token_type": "Bearer",
    "expires_in": "XXXX",
    "id_token": "XXXX"
}

▶ POST Try it out

POST https://api.thebridge.dev/auth/token

Request Body (JSON)

Use the simpler shorthand endpoint /url/login to initiate the login flow. The Bridge will collect your default config and issue the OAuth 2.0 flow.

HTTP Request

GET https://api.thebridge.dev/auth/url/login/:YOUR_APP_ID

Query Parameters

Parameter	Type	Required	Description
`redirectUri`	`string`	Optional	Target URI for redirect after auth. Defaults to your App `defaultCallbackUri`
`state`	`string`	Optional	Resume a state in your app
`responseType`	`string`	Optional	`code` or `id_token`
`forceFederation`	`string`	Optional	`ms-azure-ad`, `google`, or `saml`
`federationConnection`	`string`	Optional	Federation connection ID for SAML flows

You should redirect the user agent to this endpoint. This is not an API-to-API call. No x-api-key header is required; the App ID is in the URL path.

Try it

▶ GET Try it out

GET https://api.thebridge.dev/auth/url/login/:YOUR_APP_ID

YOUR_APP_ID URL parameter The ID of your app

Use the shorthand endpoint /url/signup to initiate the signup flow.

HTTP Request

GET https://api.thebridge.dev/auth/url/signup/:YOUR_APP_ID

Query Parameters

Parameter	Type	Required	Description
`redirectUri`	`string`	Optional	Target URI for redirect after auth. Defaults to your App `defaultCallbackUri`
`state`	`string`	Optional	Resume a state in your app
`signupPlan`	`string`	Optional	Key to an existing plan for the new tenant to subscribe to
`signupCurrency`	`string`	Optional	Currency matching one of the prices in the plan
`signupRecurrenceInterval`	`string`	Optional	Interval matching one of the prices in the plan

You should redirect the user agent to this endpoint. This is not an API-to-API call. No x-api-key header is required; the App ID is in the URL path.

Try it

▶ GET Try it out

GET https://api.thebridge.dev/auth/url/signup/:YOUR_APP_ID

YOUR_APP_ID URL parameter The ID of your app

Shorthand Get Tokens

Get new tokens using a simplified endpoint with fewer parameters.

HTTP Request

POST https://api.thebridge.dev/auth/token/:grantType/:YOUR_APP_ID

Body Parameters

Parameter	Type	Required	Description
`code`	`string`	Optional	Required for `code` grant. The authorization code
`refreshToken`	`string`	Optional	Required for `refresh` grant. The refresh token
`redirectUri`	`string`	Optional	Optional for code grant. Defaults to your App `defaultCallbackUri`

Response `HTTP 200`

HTTP 200 — Returns access token, refresh token, id_token, and user_profile.

Request example

# Exchange code for tokens
curl --request POST 'https://api.thebridge.dev/auth/token/code/YOUR_APP_ID' \
--header 'Content-Type: application/json' \
--data-raw '{ "code": "XXXX" }'

# Refresh tokens
curl --request POST 'https://api.thebridge.dev/auth/token/refresh/YOUR_APP_ID' \
--header 'Content-Type: application/json' \
--data-raw '{ "refreshToken": "XXXX" }'

Response example:

{
    "access_token": "XXXX",
    "refresh_token": "XXXX",
    "token_type": "Bearer",
    "expires_in": "XXXX",
    "id_token": "XXXX",
    "user_profile": {
        "sub": "63d25a9e0796d40008680f9a",
        "name": "John Doe",
        "family_name": "Doe",
        "given_name": "John",
        "preferred_username": "john@example.com",
        "locale": "en",
        "email": "john@example.com",
        "email_verified": true,
        "onboarded": true,
        "tenant_id": "63d25a9e0796d40008680f96",
        "tenant_name": "Johns Family",
        "tenant_locale": "en",
        "tenant_logo": ""
    }
}

Handover Code

Returns a handover code used when redirecting to or displaying The Bridge hosted views and user interactions. The code is short-lived and should be consumed immediately.

HTTP Request

POST https://api.thebridge.dev/auth/handover/code/:YOUR_APP_ID

Body Parameters

Parameter	Type	Required	Description
`accessToken`	`string`	Required	A valid user access token

Response `HTTP 200`

HTTP 200 — Returns a short-lived handover code.

Request example

curl --request POST 'https://api.thebridge.dev/auth/handover/code/YOUR_APP_ID' \
--header 'Content-Type: application/json' \
--data-raw '{ "accessToken": "XXXX" }'

Response example:

{
    "code": "XXXX"
}

▶ POST Try it out

POST https://api.thebridge.dev/auth/handover/code/YOUR_APP_ID

x-api-key required Stored in session memory only. Never persisted.

YOUR_APP_ID URL parameter The ID of your app

Request Body (JSON)

User Authentication

Authorize

HTTP Request

Query Parameters

Get Tokens

HTTP Request

Body Parameters

Response HTTP 200

Shorthand Authorize (Login)

HTTP Request

Query Parameters

Shorthand Signup

HTTP Request

Query Parameters

Shorthand Get Tokens

HTTP Request

Body Parameters

Response HTTP 200

Handover Code

HTTP Request

Body Parameters

Response HTTP 200

Response `HTTP 200`

Response `HTTP 200`

Response `HTTP 200`