> For the complete documentation index, see [llms.txt](https://docs.api.ecoinvent.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.api.ecoinvent.org/getting-started/delegated-authentication.md).

# Delegated Authentication

Delegated authentication allows your application to identify an ecoinvent user and determine which ecoinvent data they are licensed to access without handling their credentials directly.

Instead of managing ecoinvent usernames and passwords, your application redirects users to the ecoinvent login page. After they authenticate and grant consent, you receive a token you can use to query the API on their behalf and retrieve their license and access entitlements.

{% hint style="info" %}
Delegated authentication must be explicitly enabled for your account. [Contact us](mailto:sales@ecoinvent.org) to request access before getting started.
{% endhint %}

### How It Works

The integration uses the **OAuth 2.0 Authorization Code Flow**. At a high level:

1. Your app redirects the user to the ecoinvent login page
2. The user authenticates and consents to your app linking their account
3. ecoinvent redirects back to your app with a short-lived authorization code
4. Your server exchanges that code for an access token
5. You use the access token to call the ecoinvent API and retrieve the user's licence and data entitlements

### Prerequisites

#### 1. Request feature enablement

[Contact](mailto:sales@ecoinvent.org) the ecoinvent team to have delegated authentication enabled for your account. Once enabled, your credentials will be available in the [accounts portal](https://accounts.ecoinvent.org/api).

#### 2. Retrieve your credentials

Go to [accounts portal](https://accounts.ecoinvent.org) to find:

| Credential      | Description                                                                                  |
| --------------- | -------------------------------------------------------------------------------------------- |
| `client_id`     | Your application's unique identifier                                                         |
| `client_secret` | Your application's secret key - never expose this in client-side code or public repositories |

#### 3. Configure your application

Also in [accounts portal](https://accounts.ecoinvent.org), set the following fields. These are displayed to the user on the ecoinvent consent screen:

<table><thead><tr><th width="219">Field</th><th>Description</th></tr></thead><tbody><tr><td>App Name</td><td>Display name shown to users (e.g. <code>MyApp</code>)</td></tr><tr><td>App Description</td><td>Short description of why your app needs access</td></tr><tr><td>Logo URI</td><td>HTTPS URL of your app's logo shown on the consent screen</td></tr><tr><td>Redirect URIs</td><td>The URLs in your app that ecoinvent redirects to after login. Must match exactly in every request, wild cards are accepted.</td></tr></tbody></table>

### Endpoints

All endpoints are on the ecoinvent SSO server:

<table><thead><tr><th width="178">Endpoint</th><th>URL</th></tr></thead><tbody><tr><td>Authorization</td><td><code>https://sso.ecoinvent.org/realms/ecoinvent/protocol/openid-connect/auth</code></td></tr><tr><td>Token</td><td><code>https://sso.ecoinvent.org/realms/ecoinvent/protocol/openid-connect/token</code></td></tr><tr><td>Revoke</td><td><code>https://sso.ecoinvent.org/realms/ecoinvent/protocol/openid-connect/revoke</code></td></tr></tbody></table>

### The Flow

#### Step 1 - Redirect the user to ecoinvent

Construct the authorization URL and redirect the user's browser to it:

```bash
https://sso.ecoinvent.org/realms/ecoinvent/protocol/openid-connect/auth
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fyourapp.example.com%2Fcallback
  &state=RANDOM_CSRF_TOKEN
```

<table><thead><tr><th width="193">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><code>response_type</code></td><td>Must be <code>code</code></td></tr><tr><td><code>client_id</code></td><td>Your client ID from <code>accounts.ecoinvent.org</code></td></tr><tr><td><code>redirect_uri</code></td><td>Must exactly match your registered URI (URL-encoded)</td></tr><tr><td><code>state</code></td><td>A random value you generate. Returned after login, verify it matches to prevent CSRF attacks</td></tr></tbody></table>

#### Step 2 - User authenticates and consents

On the ecoinvent SSO page, the user logs in and is shown a consent screen with your app's name, logo, and description. They approve the connection between their ecoinvent account and your application.

{% hint style="info" %}
Users only see the consent screen the first time they authorize your app, or after revoking access. On subsequent logins they are redirected immediately.
{% endhint %}

#### Step 3 - Exchange the authorization code for tokens

After consent, ecoinvent redirects to your `redirect_uri` with a code:

```
https://yourapp.example.com/callback?code=AUTHORIZATION_CODE&state=YOUR_STATE
```

**Verify the `state` value matches what you sent before continuing.**

Then exchange the code for tokens from your server:

```bash
curl -X POST \
  https://sso.ecoinvent.org/realms/ecoinvent/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'code=AUTHORIZATION_CODE' \
  -d 'redirect_uri=https://yourapp.example.com/callback'
```

Response:

```json
{
  "access_token":  "eyJhbGciOiJSUzI1NiIsInR5...",
  "token_type":    "Bearer",
  "expires_in":    300,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5...",
  "refresh_expires_in":2592000,
  "session_state": "abc123..."
}
```

<table><thead><tr><th width="179.6666259765625">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>access_token</code></td><td>Short-lived token (typically 5 minutes) used to call the ecoinvent API</td></tr><tr><td><code>expires_in</code></td><td>Seconds until the access token expires</td></tr><tr><td><code>refresh_token</code></td><td>Long-lived token used to obtain new access tokens without re-authenticating</td></tr></tbody></table>

The ecoinvent SSO is an OpenID Connect (OIDC) server, so the access token is a signed JWT. You can decode it directly to read claims such as `username`, useful for surfacing the linked account identity in your UI. Alternatively, call the `userinfo` endpoint for a canonical JSON representation:

```bash
curl -X GET \
  https://sso.ecoinvent.org/realms/ecoinvent/protocol/openid-connect/userinfo \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

#### Step 4 - Query the user's license and data access

Use the access token to call the ecoinvent API and retrieve what data the user is entitled to access based on their license:

```bash
curl -X GET \
  https://api.ecoinvent.org/v3/api1/versions \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

The `/versions` endpoint returns a list of accessible releases. Each entry includes the version name, public release date and system model:

```json
{
  "total": 2,
  "results": [
    {
      "version": "3.12",
      "release_date": "2025-11-05",
      "system_model": "cutoff"
    },
    {
      "version": "3.12",
      "release_date": "2025-11-05",
      "system_model": "EN15804"
    }
  ]
}
```

Use this to gate access in your application, only offer dataset versions and system models that appear in the response for the authenticated user.

***

### Refreshing Tokens

Access tokens expire after a few minutes. Use the refresh token to obtain a new one without requiring the user to log in again:

```bash
curl -X POST \
  https://sso.ecoinvent.org/realms/ecoinvent/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'refresh_token=YOUR_REFRESH_TOKEN'
```

The response includes a new `access_token` and a new `refresh_token`. Always store the latest refresh token returned.

{% hint style="info" %}
If the refresh request fails with a `400` error, the refresh token has expired and the user must re-authorize from Step 1.
{% endhint %}

***

### Revoking Tokens (Logout)

When a user disconnects your app, revoke their tokens to terminate the session on the ecoinvent side:

```bash
curl -X POST \
  https://sso.ecoinvent.org/realms/ecoinvent/protocol/openid-connect/revoke \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'token=YOUR_REFRESH_TOKEN' \
  -d 'token_type_hint=refresh_token'
```

***

### Security Checklist

* **Never expose `client_secret`** in client-side JavaScript, mobile app binaries, or public repositories
* **Always validate `state`** on the callback to prevent CSRF attacks
* **Use HTTPS** for your redirect URI in production
* **Store tokens securely,** access tokens in memory, refresh tokens in server-side storage
* **Revoke tokens on disconnect,** don't just discard them client-side