> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.gbgplc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Single URL Login

> Sign your users in to GBG GO from your own application with a single link, without giving them GBG GO credentials or creating accounts for them in advance.

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.

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

## 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:

1. Your user asks to open GBG GO from a page in your application that they are already signed in to.
2. Your backend requests an access token with your GBG client credentials.
3. Your backend calls the Single URL Login endpoint with that token, the sub-organisation, and the user's details. GBG returns a login URL.
4. Your application presents the login URL to the user, as a link or a redirect.
5. 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](#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](/docs/go-v1/api-reference/endpoint/generate-access-token).
* **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:

<Tabs>
  <Tab title="EU">
    ```
    https://eu.platform.go.gbgplc.com/llo/
    ```
  </Tab>

  <Tab title="US">
    ```
    https://us.platform.go.gbgplc.com/llo/
    ```
  </Tab>

  <Tab title="AU">
    ```
    https://au.platform.go.gbgplc.com/llo/
    ```
  </Tab>
</Tabs>

<Tip>
  If you're unsure of your region, feel free to [contact us](https://www.gbg.com/en/contact/customer-support/).
</Tip>

## Request a login URL

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

```bash cURL theme={null}
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](/docs/go-v1/platform/investigate/overview), or `designer` for the [Journey builder](/docs/go-v1/platform/journey-builder/overview). |
| `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.

<Note>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.</Note>

### Response

A successful request returns `201 Created` with the login URL:

```json theme={null}
{
  "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.

<Info>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.</Info>

## 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.

<Warning>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.</Warning>

### 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.                                                                              |