GrandID API Documentation

GrandIDAPI
REST+JSON
Developerdocumentation
Version
Date
Author
Comments
0.1
20140325
MikaelWest
Documentiscreated
0.2
20140326
JangKee
Firstdraftdone.
0.3
20140406
MikaelWest
SOAPversion1.6
0.4
20141215
MikaelWest
JSONRESTspec.
0.5
20150119
PatrikGrinsvall
Changedendpoints
0.6
20150120
PatrikGrinsvall
Fixedspellingerrors
0.7
20150121
MikaelWest
Addedgenericinfo
0.8
20150424
PatrikGrinsvall
ChangedJSON
endpointtoversion
1.1
0.9
20150514
HjalmarWhlander
Addedaccess
marker
1.0
20150519
AbdallahSaidane
Fixlinks
1.1
20160224
HjalmarWhlander
Errormessage
information
SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala
Tel:+46184811900
www.grandid.com
Page(1/14)
Summary
1Introduction
1.1Whatyoushouldalreadyknow
1.2Prerequisites
1.3Howtodetectasuccessfulllogin
2Implementation
2.1ProcessschematicsoverGrandIDAPI
2.2ExplanationofschematicsoverGrandIDAPI
3APIdocumentation
3.1Introduction
3.2FederatedLogin
3.3GetSession
3.4FederatedDirectLogin
3.5Logout
3.5Genericerrorsmessages
4.Examples
4.1PHP
4.2.C#
Public
Thisdocumentisintendedforpublicaccess.
Tel:+46184811900
www.grandid.com
Page(2/14)
1Introduction
Inthisdocument,wespecifytheAPIandflowofeventsthatwillcoverthefunctionsofGrandID.
1.1Whatyoushouldalreadyknow
Beforeyoureadthisdocument,youshouldhaveabasicunderstandingaprogramming
languageaswellasJSON.
1.2Prerequisites
Beforestarting
apiKeyWillbesenttoyoubymail
authenticateServiceKeyWillbesenttogetherwithyourapiKey
1.3Howtodetectasuccessfulllogin
WhenyoucalltheGetSessionmethodyouwillgetajsonresponse.Ifthisresponsecontainsa
usernamekey,thismeanstheloginissuccessfull.Example:
{
"sessionId":"d04a78214b193973ecc121d2f4b3a1e0",
"username":"SE1231231231231234",
"userAttributes":{
"serialNumber":"SE1231231231231234",
"lastname":"Andersson",
"firstname":"Anders"
}
}
Note!TheuserAttributesobjectisdifferentfromeachloginmethods.
Tel:+46184811900
www.grandid.com
Page(3/14)
2Implementation
TheclientapplicationAPIneedstodotwoRESTrequesttoGrandIDAPIservicesasdescribed
below.
2.1ProcessschematicsoverGrandIDAPI
2.2
ExplanationofschematicsoverGrandID
API
1) HTTPrequestto
https://client.grandid.com/json1.1/FederatedLogin
2) withyourapiKeyandauthenticateServiceKeyasGETparametersaswellasa
callbackUrlwherewewillredirecttheauthenticateduser.
3) JSONresponsecontainingaredirectUrlandasessionIdisreturned.
4) YourwebsiteshouldnowredirectthebrowsertotheredirectUrl.
Tel:+46184811900
www.grandid.com
Page(4/14)
5) GrandIDwillauthenticatetheuserandredirecttheuserbacktotheurlspecifiedbythe
callbackUrlparameter.
6) ThewebapplicationcallstheAPImethodGetSessionat
https://client.grandid.com/json1.1/GetSession
togetherwithapiKey,
authenticateServiceKeyandthesessionidreturnedfromFederatedLogin
7) TheresponsefromGetSessionisreturningtheuserinformation.
Tel:+46184811900
www.grandid.com
Page(5/14)
3APIdocumentation
3.1Introduction
InordertoaccessGrandIDservicesfromamobile/webapplicationyouwilluseourJSONAPI.
Addressfortest:
https://clienttest.grandid.com/json1.1/
Addressforprod:
https://client.grandid.com/json1.1/
Format:
https://clienttest.grandid.com/json1.1/
<function>?apiKey=xxxxx&authenticateServiceKey=xxxxx
&callbackUrl=<urltoreturntoafterauthentication>
Examples:
https://clienttest.grandid.com/json1.1/FederatedLogin?apiKey=717234234422bc4234234b5e
485c423424d12a&authenticateServiceKey=f524234ntu82342134kr8r&callbackUrl=<urlto
returntoafterauthentication>
https://clienttest.grandid.com/json1.1/GetSession?sessionid=fenf5hf845hf4587h45&apiKey=71
7234234422bc4234234b5e485c423424d12a&authenticateServiceKey=f524234ntu82342134
kr8r
3.2FederatedLogin
Function
StringFederatedLogin(StringapiKey,StringauthenticateServiceKey,stringcallbackUrl)
Location
https://client.grandid.com/json1.1/FederatedLogin
https://clienttest.grandid.com/json1.1/FederatedLogin
Description
ThisisthefunctiontologinusinganapiKey,authenticateServiceKeyandacallbackUrl.The
returnvaluewillbeasessionidandareturnURL.
ReturnValue
Tel:+46184811900
www.grandid.com
Page(6/14)
JSONresponsefromservice.
Parametertable
Name
Type
Value
type
apiKey
String
Mandatory
authenticateServiceKey
String
callbackUrl
String
Default
value
Multiple
values
Formated
Values
No
Mandatory
No
Mandatory
No
Outputexample:
{"sessionId":"08efba128c49aa41bf62c27974f1a3cf","redirectUrl":"https://login.grandid.c
om/?sessionid=xxxxxxxxx"}
3.3GetSession
WillreturnaJSONreponsewithalltheuserdata.
Function
GetSession(Stringsessionid,StringapiKey,StringauthenticateServiceKey)
Location
https://client.grandid.com/json1.1/GetSession
https://clienttest.grandid.com/json1.1/GetSession
ReturnValue
JSONresponsefromAPI.
Parametertable
Name
Type
Value
type
Default
value
Multiple
values
Formated Values
sessionid
String
Mandatory
No
apiKey
String
Mandatory
No
String
Mandatory
No
Tel:+46184811900
www.grandid.com
Page(7/14)
Outputexample:
{"sessionId":"70011754034dc3be3c1e1d88831f0e5a","username":"mikael.westoo@eide
ntitet.se","userAttributes":{"mobile":"+46
735110424","sn":"Westoo","givenname":"Mikael","samaccountname":"mikael.westoo","tit
le":"CTO"}}
3.4FederatedDirectLogin
Function
StringFederatedDirectLogin(StringapiKey,StringauthenticateServiceKey,Stringusername,
Stringpassword)
Location
https://client.grandid.com/json1.1/FederatedDirectLogin
https://clienttest.grandid.com/json1.1/FederatedDirectLogin
Description
ThisisthefunctiontologinusinganapiKey,authenticateServiceKey,usernameandpassword
andthereturnvaluewillbeuserproperties.
ReturnValue
Parametertable
Name
Type
Value
type
apiKey
String
Mandatory
String
username
password
Default
value
Multiple
values
Formated
Values
No
Mandatory
No
String
Mandatory
No
String
Mandatory
No
Outputexample:
Tel:+46184811900
www.grandid.com
Page(8/14)
{"sessionid":"70011754034dc3be3c1e1d88831f0e5a","username":"mikael.westoo@eide
ntitet.se","userAttributes":{"mobile":"+46
735110424","sn":"Westoo","givenname":"Mikael","samaccountname":"mikael.westoo","tit
le":"CTO"}}
3.5Logout
Function
StringLogout(StringSession,StringapiKey,StringauthenticateServiceKey)
Location
https://client.grandid.com/json1.1/Logout
https://clienttest.grandid.com/json1.1/Logout
Description
ThisisthefunctiontologoutauserfromanIDP.
ReturnValue
Parametertable
Name
Type
Value
type
sessionid
String
Mandatory
apiKey
String
String
Default
value
Multiple
values
Formated Values
No
Mandatory
No
Mandatory
No
Outputexample:
{"sessiondeleted":"1"}
Tel:+46184811900
www.grandid.com
Page(9/14)
3.5Genericerrorsmessages
ReturnedasjsoninthecontainererrorObjectifacallfails.
Code
Message
TheprovidedapiKeyand
AuthenticateServiceKeycould
APIKEYNOTVALID01 notbevalidated
FIELDSNOTVALID
Incorrectcombinationof
authenticationkeys.
Meaning
Authenticationkeysarewrong
(FederatedLogin)
Authenticationkeysarewrong(GetSession)
IfyouareusingBankIDpleasealsoseeourspecificBankIDdocumentationforcustomerrors
thatcanbereturnedbytheseservices.
4.Examples
YoucandownloadGrandIDAPIexamplesfromthislink:
https://bitbucket.org/grandid/grandidclientdemo
4.1PHP
Minimalisticexample:
Tel:+46184811900
www.grandid.com
Page(10/14)
<?php
$apiKey="yourApiKey"
$authenticateServiceKey="yourAuthenticateServiceKey"
$callbackUrl="http://yoursite.com"
if(!isset($_GET['grandidsession'])){
$url="
https://clienttest.grandid.com/json1.1/FederatedLogin?authenticateServiceKey=
".
$authenticateServiceKey."&apiKey=".$apiKey."&callbackUrl=".$callbackUrl
$result=json_decode(trim(file_get_contents($url)),1)
header("Location:".$result['redirectUrl'])
}else{
$response=file_get_contents("
https://clienttest.grandid.com/json1.1/GetSession?authenticateServiceKey=
".
$authenticateServiceKey."&apiKey=".$apiKey."&sessionid=".$_GET['grandidsession'])
echo"<pre>".print_r(json_decode($response,1),1)."</pre>"
}
HereisaPHPexampleonhowtousetheGrandidAPI.
<?php
/**
*GrandIDAPIexampleusage
*ReturnJSON
*v2.0.3
*@authorGrandid
*/
/**
*@varstringServiceUrl
*/
$service_url='https://client.grandid.com'
/**
*@varstringapiKey
*/
$apiKey="APIKEY"
/**
*@varstringauthenticateServiceKey
*/
$authenticateServiceKey="AUTHENTICATESERVICEKEY"
/**
*@varstringcallbackUrl
*/
$callbackUrl=(($_SERVER['SERVER_PROTOCOL']=='HTTP/1.1')?"http://":"https://").
$_SERVER['HTTP_HOST']."".$_SERVER['REQUEST_URI']
if(!isset($_GET['grandidsession'])){
Tel:+46184811900
www.grandid.com
Page(11/14)
//SettherequestURL
$url=sprintf("%s/json1.1/FederatedLogin?apiKey=%s&authenticateServiceKey=%s&callbackUrl=%s",
$service_url,$apiKey,$authenticateServiceKey,urlencode($callbackUrl))
//IssuetherequesttotheGrandidRestService
$response=file_get_contents($url)
//DecodetheJSONresponse
$login_response=json_decode($response)
//GettheRedirectUrlfromtheresult
print'<h1>Login</h1>'
print'<aclass="btnbtndefault"href="'.$login_response>redirectUrl.'"role="button">Clickhereto
login</a>'
}else{
//SettherequestURLtoretrieveUserProfile
$url=sprintf("%s/json1.1/GetSession?apiKey=%s&authenticateServiceKey=%s&sessionid=%s",
$service_url,$apiKey,$authenticateServiceKey,$_GET['grandidsession'])
//IssuetherequesttotheGrandIDAPI
$response=file_get_contents($url)
//Profileinformationforthecurrentuser
print'<h1>Profileinformationforthecurrentuser</h1>'
print'<pre><code>'
print$response
print'</code></pre>'
}
4.2.C#
usingSystem
usingSystem.Collections.Generic
usingSystem.IO
usingSystem.Linq
usingSystem.Net
usingSystem.Text
usingSystem.Threading.Tasks
/**
*GrandIDAPIexampleusage
*ReturnJSON
*v2.0.3
Tel:+46184811900
www.grandid.com
Page(12/14)
*@authorGrandid
*/
namespaceGrandidRest
{
classGrandidRest
{
/**
*@varstringServiceUrl
*/
staticstringservice_url="https://client.grandid.com"
///<<<PARAMETERSNEEDTOBECHANGEDIFYOUCALLADIFFERENTFLOWCONTROL(LOGIN
METHOD)
/**
*@varstringapiKey
*/
staticstringapiKey="APIKEY"
/**
*@varstringauthenticateServiceKey
*/
staticstringauthenticateServiceKey="AUTHENTICATESERVICEKEY"
///>>>PARAMETERSNEEDTOBECHANGEDIFYOUCALLADIFFERENTFLOWCONTROL(LOGIN
METHOD)
/**
*@varstringcallbackUrl
*/
staticstringcallbackUrl="http://yourdomain.com/yourlocalfiles.aspx"
/**
*Thefollowingmethodissuesarequestandreturnstheentireresponseasonelongstring
*/
publicstaticstringHttpGet(stringrequestUrl)
try
HttpWebRequestrequest=WebRequest.Create(requestUrl)asHttpWebRequest
using(HttpWebResponseresponse=request.GetResponse()asHttpWebResponse)
if(response.StatusCode!=HttpStatusCode.OK)
thrownewException(String.Format(
"Servererror(HTTP{0}:{1}).",
response.StatusCode,
response.StatusDescription))
stringresult=null
StreamReaderreader=newStreamReader(response.GetResponseStream())
result=reader.ReadToEnd()
returnresult
catch(Exceptione)
Tel:+46184811900
www.grandid.com
Page(13/14)
Console.WriteLine(e.Message)
returnnull
/**
*getLoginurl
*/
publicstringLoginRequest()
return
HttpGet(String.Format("{0}/json1.1/FederatedLogin?apiKey={1}&authenticateServiceKey={2}&callbackUrl={3
}",service_url,apiKey,authenticateServiceKey,callbackUrl))
/**
*GetProfileinformationforthecurrentuser
*/
publicstringGetUserProfile(stringgrandidsession)
return
HttpGet(String.Format("{0}/json1.1/GetSession?apiKey={1}&authenticateServiceKey={2}&sessionid={3}",
service_url,apiKey,authenticateServiceKey,grandidsession))
}
}
Tel:+46184811900
www.grandid.com
Page(14/14)

GrandID API Documentation

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

GrandID API Documentation

Transféré par

Droits d'auteur :

Formats disponibles

GrandIDAPI

Vous aimerez peut-être aussi