Draft: Work in Progress
This document describes the SWAN Operator end points used by User Interface Providers (UIPs) and consumers of the SWAN data.
The document assumes the reader is familiar with the SWAN concepts.
The term User Interface Provider (UIP) is used to signify a caller with the purpose of retrieving raw SWAN data to provide a User Interface. In practice this will typically be a CMP but could be any party with the requisite access to the SWAN Network.
All the SWAN endpoints will require the mandatory parameter accessKey unless specified otherwise. This is a unique string provided by the SWAN Operator to the consumer. The accessKey must never be shared with any other party. For this reason, these APIs should only ever be used from server-side web requests.
SWAN’s access control mechanism should block requests that contain HTTP headers commonly associated with web browsers but that would not present from a server-to-server request in order to prevent accidental leakage of the accessKey.
In any case the sharing of a SWAN accessKey outside the entity that is entitled to use it would be considered a violation of the SWAN Network agreement and likely result in the entity being banned from participation in SWAN.
Six fields form the SWAN data model.
| Name | Format | Description |
|---|---|---|
| String | The original email address the user entered. Only available for the decrypt-raw end point for the purposes of providing a User Interface by the User Interface Provider. Can not be made available any other party or used for any other purpose. | |
| Pref | OWID | The preferences chosen by the user. If missing or empty the rest of the data can not be used until a specific value has been set by the user. |
| SID | OWID | The Signed in Identifier generated from the Email using a hash algorithm by the SWAN Operator. |
| Stop | String | A carriage and line feed separated list of advert identifiers that should not be used in response for advertising. |
| SWID | OWID | The globally unique identifier for the web browser generated by the SWAN Operator. |
| Val | String (Date) | A date RFC3339 form date and time string returned from some operations to indicate when the date returned should be revalidated with SWAN. |
All end points are prefixed with the /swan/api/v1/ path prefix. The path
segment that follows describes the action that the end point will perform. For
example; to fetch SWAN data from an encrypted string the fetch action is
used resulting in the path /swan/api/v1/fetch.
Unless specified otherwise all end points support both HTTP GET and POST methods.
SWAN’s data is only stored with the web browser. The fetch action is used to generate a URL that the caller should direct the web browser to in order to receive a response in the future that will contain the SWAN data. Use of the URL will typically result in one, but on first use and at other times more redirects before the browser returns to the caller.
| Parameter | Validation | Description | Example |
|---|---|---|---|
| accessKey | Mandatory | 123 |
|
| accessNode | Optional | The access node of the SWAN Operator that will be used to perform the decrypt action when control returns to the caller. If this is not provided, then the same SWAN Operator access node as the one being called will be used. This parameter is provided so that UIPs can pass an encrypted response to a publisher where they use different SWAN Operators. | ap2.swan-operator.com |
| backgroundColor | Optional | The HTML color for the background of the progress page. | #111111 |
| browserWarning | Optional | A floating-point number between 0 and 1 to indicate the probability of a warning being displayed if the browser is suspected of removing the cookies upon which SWAN relies. This is used by the SWAN Network to advise users how to modify their browser settings to avoid frequent requests for consent preferences. | 0.5 |
| displayUserInterface | Optional | Boolean indicator for the display of the progress user interface. Defaults to true. | true |
| message | Optional | The message to display above the progress indicator if enabled during the operation. Along with the title this attribute enables callers to communicate with the user and set expectations. | Hang tight. We’re just fetching your preferences. |
| messageColor | Optional | The HTML color to use for the message text. | Blue |
| nodeCount | Optional | An integer number greater than 1 to indicate the number of nodes that should be used for the operation. | 15 |
| postMessageOnComplete | Optional | Boolean indicator to determine if a window.postMessages should be used to return the encrypted response from the storage operation. If set to false then the web browsers navigation returns to the URL. Defaults to false. | False |
| pref | Optional | The current preferences OWID being used by the caller. Used if the data has been removed from the SWAN network, perhaps by tracking prevention techniques. | Nx09ZGRCrt8kByjl_HKA |
| progressColor | Optional | The HTML color for the progress indicator. | Red |
| remoteAddr | Optional | The IP address of the web browser as observed by the requesting server. Used to calculate the home node and reduce the number of redirects. | 23.245.23.65 |
| returnUrl | Mandatory | The complete URL that the web browser should return to when the operation completes. The encrypted data will be appended to this URL. If the postMessageOnComplete parameter is true then the value will be used to post the message to the correct window. | https://publisher.com/article |
| Stop | Optional | The current stopped advert identifiers being used by the caller. Used if the data has been removed from the SWAN network, perhaps by tracking prevention techniques. | cool-bikes.uk |
| swid | Optional | The current SWID OWID known to the caller. Used if the data has been removed from the SWAN network, perhaps by tracking prevention techniques. | Nx09ZGRCrt8kByjl_HKA |
| title | Optional | The title to display in the browser window during the operation. | Getting your preferences |
| X-Forwarded-For | Optional | The HTTP header value for X-Forwarded-For as provided to the requesting web server. Used to calculate the home node and reduce the number of redirects. | 23.245.23.65 |
The operation will fail with a bad request or not authorized response under the following conditions.
-
The access key is invalid.
-
The request is made from a web browser.
-
Mandatory fields are missing.
If the optional SWID, stop or pref parameters provided are not valid OWIDs that can be verified by the creator, they are ignored. The SWID must also have been created by a SWAN access node that is known to the SWAN access node being used to be accepted. This approach provides SWAN participants that contract with SWAN Operators to help the network retain data over a longer period of time when used with web browsers that seek to interfere with the cookie persistence of some domains.
The email address is not available as an optional parameter because it will never be known to the caller that is seeking to retrieve the SWAN data for the purposes of supporting advertising.
The following GET HTTP requests to a SWAN Operator using the domain swan-operator.com for the access node, will result in a URL being returned.
https://swan-operator.com/swan/api/v1/fetch?returnUrl=http%3A%2F%2Fnew-pork-limes.uk%2F&accessKey=[YOUR ACCESS KEY]
https://swan-operator.com/swan/api/v1/fetch?backgroundColor=%23fff&displayUserInterface=true&message=Getting+things+ready.+New+Pork+Limes+rocks%21&messageColor=%23343a40&postMessageOnComplete=false&progressColor=%236c757d&remoteAddr=127.0.0.1%3A63639&returnUrl=http%3A%2F%2Fnew-pork-limes.uk%2F&title=Your+Preference+Management&accessKey=[YOUR ACCESS KEY]
Assuming the accessKey is valid, and a return URL is provided, and the request is made from a server and not a web browser, the response will be a URL that must be used to navigate the browser window to within the next few seconds. The path of the response URL includes encrypted data that is used exclusively by the SWAN Operators.
http://swan-home-node.com/MTYuNTFkYi51azE2...uUXCQttStd0-vfNw
When the browser requests the return URL the encrypted data to be used in the Decrypt action is appended.
The data takes an encrypted string, typically returned to the caller via another method such as in a URL path segment or in the content of a client side postMessage. The Fetch action described previously is usually called prior to the decrypt action.
A decrypted version of the input for use by the caller under the terms of the SWAN Model Terms is returned.
The encrypted input data must be generated specifically with the intention of the SWAN Operator being called decrypting it. The operation will fail otherwise.
| Parameter | Validation | Example |
|---|---|---|
| accessKey | Mandatory | 123 |
| encrypted | Mandatory | 5dq6LhxaSBF…Nx09ZGRCrt8kByjl_HKA_1DscE7d4xLXVbz0_l1c |
<https://swan-operator.com/swan/api/v1/decrypt?accessKey=123&encrypted=5dq6LhxaSBF…Nx09ZGRCrt8kByjl_HKA_1DscE7d4xLXVbz0_l1c>
The operation will fail with a Bad Request response under the following conditions.
-
The access key is invalid.
-
The request is made from a web browser.
-
The encrypted data has been corrupted and cannot be decoded.
-
The encrypted data was intended for a different SWAN Operator and can therefore not be decrypted by the one called.
-
The time period for the validity of the data has elapsed. The default is 20 seconds from the point that the encryption occurred.
Four SWAN fields are returned. Each field has four attributes associated with them that are described in the following table.
| Attribute | Format | Description |
|---|---|---|
| Key | The SWAN data field name | String |
| Created | UTC date and time string | The date and time when the data was created in the SWAN network. |
| Expires | UTC date and time string | The data and time after which any copies of the data should no longer be used and the value revalidated with SWAN. Typically used by the caller when setting the expiry time of any cookies. |
| Value | Base 64 encoded string with the value |
The four SWAN data items available for readonly operation and distribution exclusively to SWAN participants bound by the Model Terms are returned.
[
{
"Key": "sid",
"Created": "2021-03-28T00:00:00Z",
"Expires": "2021-03-28T11:33:56.4466785Z",
"Value": "AjUxZGEudWsAJfEJAB… df9/uXPU="
},
{
"Key": "swid",
"Created": "2021-03-28T00:00:00Z",
"Expires": "2021-03-28T11:33:56.4466785Z",
"Value": "AjUxZGEudWsAo/AJ…X6rpasa6xjJFg=="
},
{
"Key": "stop",
"Created": "2021-03-28T00:00:00Z",
"Expires": "2021-03-28T11:33:56.4466785Z",
"Value": null
},
{
"Key": "pref",
"Created": "2021-03-28T00:00:00Z",
"Expires": "2021-03-28T11:33:56.4466785Z",
"Value": "AmNtcC5zd2FuLWRlbW8…AkY/HAZI="
},
{
"Key": "val",
"Created": "2021-03-28T00:00:00Z",
"Expires": "2021-03-28T11:33:56.4466785Z",
"Value": "2006-01-02T15:04:05Z07:00"
}
]
The publisher receives a URL of the following form.
http://publisher.com/5dq6LhxaSBF…Nx09ZGRCrt8kByjl_HKA_1DscE7d4xLXVbz0_l1c
The last segment of the path is the encrypted SWAN data that needs to be decrypted and turned into usable SWAN data. The publisher is responsible for extracting the input data.
The decrypt-raw action takes the same parameters as the decrypt operation.
However, it returns the information that a User Interface Provider needs to
display the user interface along with the data needed to use when using the
“update” action to update the SWAN network and return the web browser to the
caller.
The data returned from decrypt-raw can never be used for any purpose other
than to provision a user interface. This is a strict requirement of the Model
Terms.
| Attribute | Format | Description |
|---|---|---|
| The SWAN data field name | String | |
| swid | UTC date and time string | The date and time when the data was created in the SWAN network. |
| pref | UTC date and time string | The data and time after which any copies of the data should no longer be used and the value revalidated with SWAN. Typically used by the caller when setting the expiry time of any cookies. |
| accessNode backgroundColor displayUserInterface message messageColor postMessageOnComplete progressColor returnUrl title | The same meaning as those provided as input to the fetch and update actions. |
[
{
"accessNode": "swan-acess-node.com",
"backgroundColor": "#f5f5f5",
"displayUserInterface": "true",
"email": "[email protected]",
"message": "Hang tight. We're getting things ready.",
"messageColor": "darkslategray",
"postMessageOnComplete": "false",
"pref": "on",
"progressColor": "darkgreen",
"returnUrl": "http://new-pork-limes.uk/",
"swid": "AjUxZGEudWsAf/AJABAAAABELOODXltP4q2r0aTO0v4GlzOu0WiLOi+6Av4QMgwv9ZL/yIQvmY0CCBhKIFKduS/2e2QQDoFIHrOGga4cHM27Tskgjx+JlITydAckF2b3Ug",
"title": "SWAN Demo"
}
]
User Interface Providers (UIPs) will be able to update the SWAN network with the SWID,
User Interface Providers (UIPs) can use this update action to update the SWAN network. The following fields are passed to the transaction.
| Attribute | Format | Description |
|---|---|---|
| OWID | The raw email address contained in the payload of an OWID generated by the UIP. | |
| pref | OWID | The preference string contained in the payload of an OWID generated by the UIP. |
| swid | OWID | The SWID as an OWID generated by the SWAN Operator that created it via a call to create SWID. |
| accessNode backgroundColor displayUserInterface message messageColor postMessageOnComplete progressColor remoteAddr returnUrl title | The same meaning as those provided as input to the fetch and update actions. |
[TO BE COMPLETE]
[TO BE COMPLETE]
[TO BE COMPLETE]
[TO BE COMPLETE]