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.

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

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.

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

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.

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

Tel:+46184811900
www.grandid.com
Page(4/14)

5) GrandIDwillauthenticatetheuserandredirecttheuserbacktotheurlspecifiedbythe
callbackUrlparameter.
6) ThewebapplicationcallstheAPImethodGetSessionat
https://client.grandid.com/json1.1/GetSession
togetherwithapiKey,
authenticateServiceKeyandthesessionidreturnedfromFederatedLogin
7) TheresponsefromGetSessionisreturningtheuserinformation.

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

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

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

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

authenticateServiceKey

String

Mandatory

No

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

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
JSONresponsefromservice.

Parametertable
Name

Type

Value
type

apiKey

String

Mandatory

authenticateServiceKey

String

username
password

Default
value

Multiple
values

Formated

Values

No

Mandatory

No

String

Mandatory

No

String

Mandatory

No

Outputexample:

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

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
JSONresponsefromservice.

Parametertable
Name

Type

Value
type

sessionid

String

Mandatory

apiKey

String

authenticateServiceKey

String

Default
value

Multiple
values

Formated Values

No

Mandatory

No

Mandatory

No

Outputexample:

{"sessiondeleted":"1"}

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

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:

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

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'])){

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

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

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

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)

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

Tel:+46184811900
www.grandid.com
Page(13/14)

Console.WriteLine(e.Message)

returnnull

/**

*getLoginurl

*/

publicstringLoginRequest()

//IssuetherequesttotheGrandidRestService

return
HttpGet(String.Format("{0}/json1.1/FederatedLogin?apiKey={1}&authenticateServiceKey={2}&callbackUrl={3
}",service_url,apiKey,authenticateServiceKey,callbackUrl))

/**

*GetProfileinformationforthecurrentuser

*/

publicstringGetUserProfile(stringgrandidsession)

//IssuetherequesttotheGrandidRestService

return
HttpGet(String.Format("{0}/json1.1/GetSession?apiKey={1}&authenticateServiceKey={2}&sessionid={3}",
service_url,apiKey,authenticateServiceKey,grandidsession))

}
}

SvenskeidentitetABSvartbcksgatan5
Org.nr:556776699275320Uppsala

Tel:+46184811900
www.grandid.com
Page(14/14)