Difference between revisions of "API SSO"

From zFairs Contest Management
(Remove username/password API auth; ApiKey only)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
== SSO ==
 
== SSO ==
−
You can use our api to get a SSO url that will allow you to sign-in a user when they go to that url. This token is only good for one time and expires in just a few minutes. You should only create this token when the user has requested to sso into your zFairs site. If you want to get an SSO URL you need to POST a message to your site. Below is an example of what needs to be posted.
+
Builds a one-time single sign-on URL for an existing person so they can land in the fair already logged in.
  
−
fetch('/api/data/sso', {
+
=== Authentication ===
−
method:'POST',
+
All data API calls are <code>POST</code> (unless noted) with JSON body:
−
headers:{'Content-Type': 'application/json'},
 
−
body: JSON.stringify({
 
−
Username:'admin username',
 
−
Password: 'password',
 
−
FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', //This value can be found in your url it's the value of f
 
−
Body: {
 
−
PersonId:'persons id (36 char GUID)' //Required
 
−
}
 
−
})
 
−
})
 
−
.then(response => response.json())
 
−
.then(data=>{console.log('Success: ',data);})
 
−
.catch((error)=>{console.log('Error: ', error);});
 
  
−
== Where to get values ==
+
{| class="wikitable"
−
You will get the person when you use our API to add the person or project. Do not use the project key.
+
|-
 +
! Field !! Required !! Description
 +
|-
 +
| <code>ApiKey</code> || Yes || Private API key for your site.
 +
|-
 +
| <code>FairId</code> || Yes || Fair GUID from the site URL (<code>f</code> query parameter).
 +
|-
 +
| <code>Body</code> || Depends || Request payload. Use <code>{}</code> when no body fields are needed.
 +
|}
  
  
 +
Calls must be run '''server-side''' — do not expose your API key in a browser.
  
−
<br/><br/><br/><br/>
+
=== Response envelope ===
 +
Most endpoints return:
 +
 
 +
<pre>
 +
{
 +
  Success: true,
 +
  Message: null,  // error text when Success is false
 +
  Body: { ... }    // endpoint-specific payload
 +
}
 +
</pre>
 +
 
 +
 
 +
=== Request ===
 +
<syntaxhighlight lang="JavaScript" line>
 +
fetch('/api/data/SSO', {
 +
    method:'POST',
 +
    headers:{'Content-Type': 'application/json'},
 +
    body: JSON.stringify({
 +
            ApiKey:'<Private key>',
 +
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', // value of f in your URL
 +
            Body: {
 +
PersonId: "32161f13-474b-442f-ac1f-edca7348e000"
 +
}
 +
        })
 +
})
 +
.then(response => response.json())
 +
.then(data=>{console.log('Success: ',data);})
 +
.catch((error)=>{console.log('Error: ', error);});
 +
</syntaxhighlight>
 +
 
 +
=== Response ===
 +
On success:
 +
 
 +
<pre>
 +
{
 +
  Success: true,
 +
  Message: null,
 +
  Body: {
 +
    Sso: "https://yoursite.zfairs.com/...?f=...&sso=TOKEN"
 +
  }
 +
}
 +
</pre>
 +
 
 +
Person not found:
 +
 
 +
<pre>
 +
{ Success: false, Message: "Person not found!" }
 +
</pre>
 +
 
 +
 
 +
=== Field notes ===
 +
* <code>PersonId</code> is the person's public GUID (from add person, teachers, judges, participants).
 +
* The person must belong to the same client as the fair.
 +
* Treat the returned URL as a secret one-time login link; do not log it publicly.
 +
 
 +
 
 +
=== Related APIs ===
 +
* [[API Add Person]]
 +
* [[API Get Teachers]] / [[API Get Judges]] / [[API Get participants]]
 +
 
 +
 
 +
<br/><br/>
 
[[Category: API]]
 
[[Category: API]]

Latest revision as of 12:55, 25 July 2026

SSO

Builds a one-time single sign-on URL for an existing person so they can land in the fair already logged in.

Authentication

All data API calls are POST (unless noted) with JSON body:

Field Required Description
ApiKey Yes Private API key for your site.
FairId Yes Fair GUID from the site URL (f query parameter).
Body Depends Request payload. Use {} when no body fields are needed.


Calls must be run server-side — do not expose your API key in a browser.

Response envelope

Most endpoints return: 

{
  Success: true,
  Message: null,   // error text when Success is false
  Body: { ... }    // endpoint-specific payload
}


Request

fetch('/api/data/SSO', {
    method:'POST',
    headers:{'Content-Type': 'application/json'},
    body: JSON.stringify({
            ApiKey:'<Private key>',
            FairId: '9df61f13-474b-442f-ac1f-edca7348ef71', // value of f in your URL
            Body: {
				PersonId: "32161f13-474b-442f-ac1f-edca7348e000"
			}
        })
})
.then(response => response.json())
.then(data=>{console.log('Success: ',data);})
.catch((error)=>{console.log('Error: ', error);});

Response

On success: 

{
  Success: true,
  Message: null,
  Body: {
    Sso: "https://yoursite.zfairs.com/...?f=...&sso=TOKEN"
  }
}

Person not found: 

{ Success: false, Message: "Person not found!" }


Field notes

  • PersonId is the person's public GUID (from add person, teachers, judges, participants).
  • The person must belong to the same client as the fair.
  • Treat the returned URL as a secret one-time login link; do not log it publicly.


Related APIs




Retrieved from "https://wiki.zFairs.com/index.php?title=API_SSO&oldid=967"