Right off, this is applicable to those clients whose voters login at a third-party website (for example, the website owned by the organization conducting the election) and are then passed over to the Skypunch website where the voter may view and submit a ballot without being prompted to login again. This is referred to as passed authentication and if it does not apply to you, what follows won't either. The other two authentication models are fully hosted–where the voter logs in at the Skypunch website to access the ballot–and fully integrated where the ballot is consumed into a third-party website and the voter never sees the Skypunch website. All three authentication models are discussed in more detail at the election model flowchart.
API Documentation
The Skypunch API documentation is available at REST API Documentation. The specific part of that documentation connected to this update is at the bottom of the page under the heading Get token for passed authentication.
The Changes
For those using passed authentication, the changes to the API are this:
- You may now include email with the data sent to the request for a passed authentication token.
- The response includes a couple of new values.
- After retrieving an authentication token, you may redirect requests to a new URL, though the old URL will live on for some time.
Passing Email
Email may now be passed as one of the request parameters just like all the others. Email is not required with this version of the API, but will become required in the next version so it makes sense to start including it now. The big benefit of providing an email is that the Skypunch system now sends an email confirmation to voters at the moment they submit a ballot–a capability that was not previously available for passed authentication elections. And now that the Skypunch email confirmation includes ballot verification data, this is of greater value than ever because previously the only way a passed authentication voter would have been able to capture ballot verification data would have been at the moment they submit their ballot.
New Values in the Response
The response to the get token endpoint is a JSON object. Previously that object contained only one key named token. The value of that key would be either the token that authenticates the voter or a message that explains why an authentication token could not be granted. The token key still exists so it is not necessary to adjust any application code. However, a couple of new keys are now included in the response. Those are message and token_issued. As the names suggest, token_issued will be a boolean yes/no value that informs as to whether or not an authentication token was issued for this request. When a token can not be issued, the message key will provide a plain-English description of why.
Redirect URL
Previously, after requesting a token for passed authentication token, an application would extract the token from the response, then perform a redirect to:
https://www.electionsonline.com/vote/sso.cfm?token=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx
You should now redirect to:
https://www.electionsonline.com/vote/login.cfm?token=xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxxxxxx
In fact, the login.cfm address isn't really new at all as it's the exact same address used by fully hosted elections where voters login at the Skypunch website. This is good because it means passed authentication elections now use the exact same authentication logic as fully hosted elections. To avoid updating any existing code, the sso.cfm address continues to live but it does absolutely nothing other than to redirect to login.cfm. In time, the sso.cfm address will cease to exist so it makes sense to update any redirects now.
