Single URL Login

Single URL Login lets you sign your users in to GBG GO from your own application. Your user clicks a link on a page you already control and lands in GBG GO, already signed in and scoped to one of your sub-organisations. Your users do not need GBG GO credentials, and you do not need to create accounts for them in advance.

GBG technical material and API paths refer to Single URL Login as LLO. Both names describe the same capability.

How it works

Single URL Login splits responsibility between you and GBG:

You confirm who your user is. Your application authenticates the user the way it already does. GBG performs no user authentication in this flow.
GBG confirms who you are. Your backend authenticates with your GBG client credentials, so GBG knows which partner is asking and which sub-organisations you can reach.

Every sign-in follows the same sequence:

Your user asks to open GBG GO from a page in your application that they are already signed in to.
Your backend requests an access token with your GBG client credentials.
Your backend calls the Single URL Login endpoint with that token, the sub-organisation, and the user’s details. GBG returns a login URL.
Your application presents the login URL to the user, as a link or a redirect.
The user opens the URL and lands in GBG GO, signed in and scoped to that sub-organisation.

Each login URL works once and expires after about five minutes, so request it at the moment your user asks for it. For more information, see Things to know.

Before you start

GBG puts the following in place for you. Contact your GBG representative if any of it is missing:

Your organisation is registered as a partner, and each sub-organisation you want to reach is a direct child of it.
Your client credentials hold the Single URL Login entitlement.
Single URL Login is enabled for your organisation.

On your side, you need the following:

Client credentials. The same client_id and client_secret you use for the rest of the GBG GO API. For the steps, see Authentication.
A server-side integration. Call the endpoint from your backend. Never expose your access token or your client credentials to the browser.
Your user’s details at the moment they ask for access. You supply the user’s email address, display name, and the sub-organisation ID with every request. There is no user registration step.
A page to render the link on. Use one of your own authenticated pages, so that only the intended user can reach the link.

You do not need an identity provider, signing keys, or OIDC endpoints of your own.

Base URL

Send Single URL Login requests to the regional endpoint that matches your deployment:

https://eu.platform.go.gbgplc.com/llo/

https://us.platform.go.gbgplc.com/llo/

https://au.platform.go.gbgplc.com/llo/

If you’re unsure of your region, feel free to contact us.

Call POST /llo/auth-context from your backend, with your access token in the Authorization header.

cURL

curl --request POST \
  --url https://eu.platform.go.gbgplc.com/llo/auth-context \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "subOrgId": "acme-eu-001",
    "userEmail": "investigator@acme.com",
    "userName": "Jane Smith",
    "targetApp": "portal"
  }'

Request fields

Field	Required	Description
`subOrgId`	Yes	The sub-organisation to sign the user in to. It must be a direct child of your partner organisation.
`userEmail`	Yes	The user’s email address. GBG GO uses it to identify the user for this session.
`userName`	Yes	The user’s display name. GBG GO splits it into a first name and a last name.
`targetApp`	Yes	Where the user lands. Use `portal` for the Investigation portal, or `designer` for the Journey builder.
`role`	No	The role to grant the user. If you omit both `role` and `permissions`, GBG GO grants the default role.
`permissions`	No	The individual permissions to grant the user, instead of a role.

Supply at most one of role and permissions. Supplying both returns a 400 response.

Region is not a request field. Each session uses the same region as the credentials you called with. Requesting a region in the body has no effect.

Response

A successful request returns 201 Created with the login URL:

{
  "loginUrl": "https://app.go.gbg.com/view/llo-start?ticket=nanoid123&target=%2Fview"
}

Present the link to your user

Follow these practices when you hand the login URL to your user:

Request the URL when your user asks to open GBG GO, not in advance. Each URL works once and expires after about five minutes.
Render it on a page your user is already authenticated on. Anyone who obtains an unused URL can sign in as that user.
Treat the URL as opaque. Do not parse or modify it. Changing the URL does not change where the user lands.
Keep it out of email, logs, and any channel you do not control.

What your user can do

If you request neither a role nor permissions, GBG GO grants the default role, investigation-viewer. It gives your user read-only access to:

View investigations.
View journey sessions and their details.
View the documents attached to a session.

It does not let the user create, change, or delete anything, and it grants no access to settings or administration.

Request different permissions

To grant something other than the default, supply either:

role, to grant a named role. The current catalogue contains one role, investigation-viewer.
permissions, to grant individual permissions in verb:resource form, for example read:journey-sessions. Each permission must be one that GBG allows partners to delegate. Contact your GBG representative for the current list.

Whatever you request is then capped:

A session never holds more than your own credentials hold. If your credentials do not hold a permission, you cannot delegate it, whatever the request body says.
A session created this way can never itself request a login URL.
If nothing you requested survives the cap, GBG denies the request rather than creating a session with no access.

If a user reports that they cannot see something you expected them to see, the most likely cause is that the permission was trimmed because your own credentials do not hold it.

Things to know

Link mechanics

One use only. Once a link has signed a user in, it cannot be used again. A second click shows a Link no longer valid page. Every sign-in needs a new request.
Expires after about five minutes. Generate links on demand. You cannot pre-generate them in batches or send them out to be used later.
No refresh token. Once your user lands, GBG GO owns the session and the link plays no further part.

Destination

Two destinations only. Choose between the Investigation portal and the Journey builder with targetApp. You cannot supply your own URL or path.
No deep linking. Your user lands on the root of the chosen destination. You cannot send a user directly to a specific journey session or case.

Access

Direct children only. subOrgId must be a direct child of your partner organisation. You cannot reach a grandchild sub-organisation in one call.
Permissions only narrow. You can grant less than your own credentials hold, never more.
Region follows your credentials. You cannot choose a region per request.

Data handling

The email address and display name you send are held only for the lifetime of the link, and are discarded when the link expires or is used. GBG GO creates no stored user record from them.
Audit records identify the user with a non-reversible reference rather than their email address. Neither the login URL nor your access token appears in an audit record.

Rate limits

Rate limits apply at the platform edge rather than at the endpoint, so the endpoint returns no 429 response. Contact your GBG representative for the limits that apply to your organisation.

Troubleshoot

Every response, successful or not, includes an X-Request-ID header. Capture it and keep it. GBG records the specific reason for a failure against that ID, so quoting it is the fastest route to a diagnosis.

Error responses state only the broad category of a failure, not the specific reason, so that they reveal nothing about your organisation structure or entitlements. Quote the X-Request-ID when you raise a support case.

Response codes

Status	Meaning	Common causes
`400`	Bad request	You supplied both `role` and `permissions`, requested a role that does not exist, or sent a malformed body.
`401`	Authentication failed	Your access token is missing, expired, or invalid, or it was not issued for your GBG client credentials. A token from a GBG GO user session is rejected here.
`403`	Access denied	Single URL Login is not enabled for your organisation, `subOrgId` is not a direct child of it, you requested more than your credentials hold, or nothing you requested could be granted.
`500`	Server error	A temporary problem issuing the link. Retry the request.

What your user sees if a link fails

Your user sees one of two pages, and they mean different things:

Page	What it means
Link no longer valid	The link has already been used, has expired, or is not recognised. This is almost always a stale or reused link. Request a new one.
Access unavailable	Access for your organisation or the sub-organisation changed between GBG issuing the link and your user opening it. Contact your GBG representative.

Common symptoms

Symptom	Likely cause
Every call returns `401`	Your client credentials are wrong or expired, or the token was not issued by GBG.
`403` for one sub-organisation, others succeed	That sub-organisation is not a direct child of your partner organisation.
`403` for every sub-organisation	Single URL Login is not enabled for your organisation, or your credentials do not hold the entitlement.
The link is issued, but shows Link no longer valid immediately	The link was already used, or more than five minutes passed before your user opened it. Check that you request the link at the moment your user asks for access.
Your user signs in, but sees less than you expected	A permission you requested was trimmed because your own credentials do not hold it.

Get Started

Platform

Developer Integration

Digital IDs

Resources

How it works

Before you start

Base URL

Request fields

Response

Present the link to your user

What your user can do

Request different permissions

Things to know

Link mechanics

Destination

Access

Data handling

Rate limits

Troubleshoot

Response codes

What your user sees if a link fails

Common symptoms

​How it works

​Before you start

​Base URL

​Request a login URL

​Request fields

​Response

​Present the link to your user

​What your user can do

​Request different permissions

​Things to know

​Link mechanics

​Destination

​Access

​Data handling

​Rate limits

​Troubleshoot

​Response codes

​What your user sees if a link fails

​Common symptoms

How it works

Before you start

Base URL

Request a login URL

Request fields

Response

Present the link to your user

What your user can do

Request different permissions

Things to know

Link mechanics

Destination

Access

Data handling

Rate limits

Troubleshoot

Response codes

What your user sees if a link fails

Common symptoms