# Single Sign On URL

Learn how to generate a URL for the hosted UI used for Single Sign On (SSO) of license users with the `/api/v4/sso_url` endpoint.

***

### Endpoint

* Method: `GET`
* Path: `/api/v4/sso_url`
* Description: Returns the Single Sign-On URL for license user authorization.

### Authentication

See [License API Authorization](/license-api/license-api-authorization.md).

#### Required headers

* `Date` (string)
* `Authorization` (string)

#### Recommended headers

* `Accept: application/json`

### Request

#### Query parameters

Required:

* `product` (string)
* `customer_account_code` (string)

Optional:

* `response_type` (string) — `code` or `token`. Default: `code`

Example request URL: `/api/v4/sso_url?product=string&customer_account_code=string` \
(You can add `&response_type=token` to enable Implicit grant, otherwise it will default \
to the Authorization Code grant)

### Examples

{% tabs %}
{% tab title="curl" %}

```bash
curl --location --request GET '/api/v4/sso_url?product=string&customer_account_code=string' \
--header 'Accept: application/json' \
--header 'Date: string' \
--header 'Authorization: string'
```

{% endtab %}

{% tab title="nodejs" %}

```javascript
var request = require('request');
var options = {
  method: 'GET',
  url: '/api/v4/sso_url?product=string&customer_account_code=string',
  headers: {
    'Accept': 'application/json',
    'Date': 'string',
    'Authorization': 'string'
  }
};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});
```

{% endtab %}

{% tab title="javascript (fetch)" %}

```javascript
var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Date", "string");
myHeaders.append("Authorization", "string");

var requestOptions = {
  method: 'GET',
  headers: myHeaders,
  redirect: 'follow'
};

fetch("/api/v4/sso_url?product=string&customer_account_code=string", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
```

{% endtab %}

{% tab title="python" %}

```python
import requests

url = "/api/v4/sso_url?product=string&customer_account_code=string"

headers = {
  "Accept": "application/json",
  "Date": "string",
  "Authorization": "string"
}

response = requests.get(url, headers=headers)
print(response.text)
```

{% endtab %}

{% tab title="ruby" %}

```ruby
require "uri"
require "net/http"

url = URI("/api/v4/sso_url?product=string&customer_account_code=string")

http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Accept"] = "application/json"
request["Date"] = "string"
request["Authorization"] = "string"

response = http.request(request)
puts response.read_body
```

{% endtab %}
{% endtabs %}

### Example success response (200)

```json
{
  "url": "https://auth.licensespring.com/realms/user-portal/protocol/openid-connect/auth?scope=openid&response_type=code&client_id=license-users&redirect_uri=http://localhost&kc_idp_hint=foo-bar",
  "openid_configuration": {
    "issuer": "https://auth.licensespring.com/realms/user-portal",
    "end_session_endpoint": "https://auth.licensespring.com/realms/user-portal/protocol/openid-connect/logout",
    "token_endpoint": "https://auth.licensespring.com/realms/user-portal/protocol/openid-connect/token",
    "introspection_endpoint": "https://auth.licensespring.com/realms/user-portal/protocol/openid-connect/token/introspect"
  }
}
```

### Authorization method

By default, authorization for SSO uses the Authorization Code grant which attaches a `code` query parameter to the `redirect_uri` once the user is verified. This code is then sent in the request body when doing license activation.

If you prefer to receive user pool tokens directly on the redirect, you can use the Implicit grant. In that case, user pool tokens (`id_token`, `access_token`, `expires_in`, and `token_type`) are attached to the `redirect_uri` (instead of `code`) once the user is verified, and the `access_token` can then be used for license activation. Be aware that this exposes user tokens in the redirect URI and results in a longer URI.\
To enable Implicit grant, add `response_type=token` to this endpoint. \
\
Example: `/api/v4/sso_url/?customer_account_code=test&product=test&response_type=token`

### Schema

<details>

<summary><strong>Request + response schema (TypeScript + JSON Schema)</strong></summary>

Request Query Parameters (TypeScript)

```typescript
type SSOURLRequestParams = {
  product: string,
  customer_account_code: string,
  response_type?: 'code' | 'token' | undefined
}
```

Request Query Parameters (JSON Schema)

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "product": { "type": "string" },
    "customer_account_code": { "type": "string" },
    "response_type": { "type": "string", "enum": ["code", "token"] }
  },
  "required": ["product", "customer_account_code"],
  "additionalProperties": false
}
</code></pre>

</details>

<details>

<summary><strong>Response body + response body schema (TypeScript + JSON Schema)</strong></summary>

Response Body (TypeScript)

```typescript
type SSOURLResponseBody = {
  url: string,
  openid_configuration: {
    issuer: string,
    end_session_endpoint: string,
    token_endpoint: string,
    introspection_endpoint: string,
  }
}
```

Response Body (JSON Schema)

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "url": { "type": "string" },
    "openid_configuration": {
      "type": "object",
      "properties": {
        "issuer": { "type": "string" },
        "end_session_endpoint": { "type": "string" },
        "token_endpoint": { "type": "string" },
        "introspection_endpoint": { "type": "string" }
      }
    }
  },
  "required": ["url"],
  "additionalProperties": false
}
```

</details>

### Errors

If an error occurs, the response will have an HTTP status code >= 400 and the response body will contain an error description in this format:

```typescript
{
  status: number,
  code: string,
  message: string
}
```

Error schema (JSON Schema)

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "number" },
    "code": { "type": "string" },
    "message": { "type": "string" }
  },
  "required": [
    "status",
    "code",
    "message"
  ],
  "additionalProperties": false
}
```

List of exceptions

> **unknown\_product** (400): Provided product was not found

> **missing\_headers** (400): Some headers are missing

> **authorization\_missing\_params** (400): Some parameters are missing in the authorization: { params }


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.licensespring.com/license-api/single-sign-on-url.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.