> For the complete documentation index, see [llms.txt](https://api-docs.devhub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api-docs.devhub.com/single-sign-on-sso/introduction.md).
# Introduction
This user guide describes the service provided for our partners, where your users can sign into the Site Builder, and optionally be redirected directly into the builder for an existing site, using your website's credentials. This is generally known as a "Single Sign-On", or SSO, system.
Contained in this document:
* [Access requirements](/single-sign-on-sso/introduction.md#access-requirements)
* [Prerequisites](/single-sign-on-sso/introduction.md#prerequisites)
* [Request parameters](/single-sign-on-sso/introduction.md#request-parameters)
* [Code examples](/single-sign-on-sso/introduction.md#code-examples)
* [Python/Django](/single-sign-on-sso/introduction.md#pythondjango-example)
* [PHP5](/single-sign-on-sso/introduction.md#php5-example)
## Access requirements
* Access has to be approved and enabled within your private label
* You will be given an OAuth "public" key (`CONSUMER_KEY`) and a "secret" key (`CONSUMER_SECRET`)
* You will also be given a base URI, signifying where the widget javascript requests will be made:
* `BASE_WIDGET_URI`: The base URI for the single sign-on (logs the user into the site management interface)
## Prerequisites
* The platform uses portions of the OAuth protocol to verify that a user has access to it's SSO system. You will need to install an OAuth library that fits in with your server technology. There are several linked to the OAuth code website.
* The widget examples shown use the jQuery JavaScript library to render itself, but any form of javascript can be used to interact with the widget
## Request Parameters
Your code will generate a signed URI, which is the main way that the API interacts with your web page. The following are the required GET request parameters for both SSO and direct-to-builder access type:
| Name | Type | Description |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `email` | `string` | The email address of the partner user |
| `partner_user_id` | `string` | This is the unique user ID you use in your user management system |
| | | |
| **Optional** | | |
| `first_name` | `string` | The first (given) name of the partner user. Will be used within the builder interface under their account settings |
| `last_name` | `string` | The last (family) name of the partner user |
For direct-to-builder access, the following parameters are also required:
| Name | Type | Description |
| ------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `partner_site_ids` | `string` | These are is the unique site IDs you have assigned to the Sites you have created under the private label. These IDs should be comma separated if passing more than one during the request. (i.e. `12345,23145`) |
## Code examples
All of the examples utilize the following jQuery snippet for displaying the SSO links on a page.
### `show-links.js`
```javascript
$(function() {
$('Login as user
')
.appendTo('#body');
$.each(sb.uris.sites, function(k, uri) {
$('Login to site ' + k + '
')
.appendTo('#body');
});
});
```
### Python/Django example
The following example uses Python and Django to generate the code necessary for the login widget to render, and direct links to the builder for specific sites. It uses the python oauth library to generate the signed oauth urls.
#### `views.py`
```python
from django.shortcuts import render_to_response
from django.template import RequestContext
from oauth.oauth import (
OAuthConsumer, OAuthRequest, OAuthSignatureMethod_HMAC_SHA1)
def generate_oauth_uri(params=None):
'''Helper function which generates the proper OAuth URI.'''
uri = BASE_WIDGET_URI
consumer = OAuthConsumer(CONSUMER_KEY, CONSUMER_SECRET)
request = OAuthRequest.from_consumer_and_token(consumer,
http_url=uri,
parameters=params)
request.sign_request(OAuthSignatureMethod_HMAC_SHA1(), consumer, '')
return request.to_url()
def single_sign_on(request):
'''The actual view'''
data = {
'partner_user_id': '1234567890',
'email': 'john@example.com',
'first_name': 'John',
'last_name': 'Doe',
'partner_site_ids': '12345',
}
return render_to_response('index.html', {
'widget_uri': generate_oauth_uri(data),
})
```
#### `index.html`
```markup
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://api-docs.devhub.com/single-sign-on-sso/introduction.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.