Scribd
Upload
201 views14 pages

GrandID API Developer Documentation

1. The document provides documentation for the GrandID API, including descriptions of its functions, parameters, examples and error messages. 2. It describes two main REST requests needed to implement authentication with GrandID - FederatedLogin to start the login process and get a redirect URL, and GetSession to retrieve user attributes after login. 3. The API functions covered include FederatedLogin, GetSession, FederatedDirectLogin, and Logout. Parameters, request formats, example responses and error codes are defined for each.

Uploaded by

rivaldoyu
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
201 views14 pages

GrandID API Developer Documentation

1. The document provides documentation for the GrandID API, including descriptions of its functions, parameters, examples and error messages. 2. It describes two main REST requests needed to implement authentication with GrandID - FederatedLogin to start the login process and get a redirect URL, and GetSession to retrieve user attributes after login. 3. The API functions covered include FederatedLogin, GetSession, FederatedDirectLogin, and Logout. Parameters, request formats, example responses and error codes are defined for each.

Uploaded by

rivaldoyu
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

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
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
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
[Link]
4.1PHP
4.2.C#

Public
Thisdocumentisintendedforpublicaccess.

SvenskeidentitetABSvartbcksgatan5
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
Page(2/14)

1Introduction

Inthisdocument,wespecifytheAPIandflowofeventsthatwillcoverthefunctionsofGrandID.

1.1Whatyoushouldalreadyknow
Beforeyoureadthisdocument,youshouldhaveabasicunderstandingaprogramming
languageaswellasJSON.

1.2Prerequisites
Beforestarting

apiKeyWillbesenttoyoubymail
authenticateServiceKeyWillbesenttogetherwithyourapiKey

1.3Howtodetectasuccessfulllogin
[Link]
usernamekey,[Link]:

{
"sessionId":"d04a78214b193973ecc121d2f4b3a1e0",
"username":"SE1231231231231234",
"userAttributes":{
"serialNumber":"SE1231231231231234",
"lastname":"Andersson",
"firstname":"Anders"
}
}

Note!TheuserAttributesobjectisdifferentfromeachloginmethods.

SvenskeidentitetABSvartbcksgatan5
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
Page(3/14)

2Implementation
TheclientapplicationAPIneedstodotwoRESTrequesttoGrandIDAPIservicesasdescribed
below.

2.1ProcessschematicsoverGrandIDAPI

2.2
ExplanationofschematicsoverGrandID
API

1) HTTPrequestto
[Link]
2) withyourapiKeyandauthenticateServiceKeyasGETparametersaswellasa
callbackUrlwherewewillredirecttheauthenticateduser.
3) JSONresponsecontainingaredirectUrlandasessionIdisreturned.
4) YourwebsiteshouldnowredirectthebrowsertotheredirectUrl.

SvenskeidentitetABSvartbcksgatan5
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
Page(4/14)

5) GrandIDwillauthenticatetheuserandredirecttheuserbacktotheurlspecifiedbythe
callbackUrlparameter.
6) ThewebapplicationcallstheAPImethodGetSessionat
[Link]
togetherwithapiKey,
authenticateServiceKeyandthesessionidreturnedfromFederatedLogin
7) TheresponsefromGetSessionisreturningtheuserinformation.

SvenskeidentitetABSvartbcksgatan5
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
Page(5/14)

3APIdocumentation
3.1Introduction
InordertoaccessGrandIDservicesfromamobile/webapplicationyouwilluseourJSONAPI.

Addressfortest:
[Link]

Addressforprod:
[Link]

Format:
[Link]
<function>?apiKey=xxxxx&authenticateServiceKey=xxxxx
&callbackUrl=<urltoreturntoafterauthentication>

Examples:
[Link]
485c423424d12a&authenticateServiceKey=f524234ntu82342134kr8r&callbackUrl=<urlto
returntoafterauthentication>

[Link]
7234234422bc4234234b5e485c423424d12a&authenticateServiceKey=f524234ntu82342134
kr8r

3.2FederatedLogin

Function
StringFederatedLogin(StringapiKey,StringauthenticateServiceKey,stringcallbackUrl)

Location
[Link]
[Link]

Description
ThisisthefunctiontologinusinganapiKey,[Link]
returnvaluewillbeasessionidandareturnURL.

ReturnValue

SvenskeidentitetABSvartbcksgatan5
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
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":"[Link]
om/?sessionid=xxxxxxxxx"}

3.3GetSession
WillreturnaJSONreponsewithalltheuserdata.

Function
GetSession(Stringsessionid,StringapiKey,StringauthenticateServiceKey)

Location
[Link]
[Link]

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
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
Page(7/14)

Outputexample:

{"sessionId":"70011754034dc3be3c1e1d88831f0e5a","username":"[Link]@eide
[Link]","userAttributes":{"mobile":"+46
735110424","sn":"Westoo","givenname":"Mikael","samaccountname":"[Link]","tit
le":"CTO"}}

3.4FederatedDirectLogin

Function
StringFederatedDirectLogin(StringapiKey,StringauthenticateServiceKey,Stringusername,
Stringpassword)

Location
[Link]
[Link]

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
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
Page(8/14)

{"sessionid":"70011754034dc3be3c1e1d88831f0e5a","username":"[Link]@eide
[Link]","userAttributes":{"mobile":"+46
735110424","sn":"Westoo","givenname":"Mikael","samaccountname":"[Link]","tit
le":"CTO"}}

3.5Logout

Function
StringLogout(StringSession,StringapiKey,StringauthenticateServiceKey)

Location
[Link]
[Link]

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
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
Page(9/14)

3.5Genericerrorsmessages

ReturnedasjsoninthecontainererrorObjectifacallfails.

Code

Message

TheprovidedapiKeyand
AuthenticateServiceKeycould
APIKEYNOTVALID01 notbevalidated
FIELDSNOTVALID

Incorrectcombinationof
authenticationkeys.

Meaning
Authenticationkeysarewrong
(FederatedLogin)
Authenticationkeysarewrong(GetSession)

IfyouareusingBankIDpleasealsoseeourspecificBankIDdocumentationforcustomerrors
thatcanbereturnedbytheseservices.

[Link]
YoucandownloadGrandIDAPIexamplesfromthislink:
[Link]

4.1PHP

Minimalisticexample:

SvenskeidentitetABSvartbcksgatan5
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
Page(10/14)

<?php
$apiKey="yourApiKey"
$authenticateServiceKey="yourAuthenticateServiceKey"
$callbackUrl="[Link]

if(!isset($_GET['grandidsession'])){
$url="
[Link]
".
$authenticateServiceKey."&apiKey=".$apiKey."&callbackUrl=".$callbackUrl
$result=json_decode(trim(file_get_contents($url)),1)
header("Location:".$result['redirectUrl'])
}else{
$response=file_get_contents("
[Link]
".
$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='[Link]

/**
*@varstringapiKey
*/
$apiKey="APIKEY"

/**
*@varstringauthenticateServiceKey
*/
$authenticateServiceKey="AUTHENTICATESERVICEKEY"

/**
*@varstringcallbackUrl
*/
$callbackUrl=(($_SERVER['SERVER_PROTOCOL']=='HTTP/1.1')?"[Link]
$_SERVER['HTTP_HOST']."".$_SERVER['REQUEST_URI']

if(!isset($_GET['grandidsession'])){

SvenskeidentitetABSvartbcksgatan5
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
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
[Link]
[Link]
[Link]
[Link]
[Link]
[Link]

/**
*GrandIDAPIexampleusage
*ReturnJSON
*v2.0.3

SvenskeidentitetABSvartbcksgatan5
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
Page(12/14)

*@authorGrandid
*/

namespaceGrandidRest
{
classGrandidRest
{

/**

*@varstringServiceUrl

*/

staticstringservice_url="[Link]

///<<<PARAMETERSNEEDTOBECHANGEDIFYOUCALLADIFFERENTFLOWCONTROL(LOGIN
METHOD)

/**

*@varstringapiKey

*/

staticstringapiKey="APIKEY"

/**

*@varstringauthenticateServiceKey

*/

staticstringauthenticateServiceKey="AUTHENTICATESERVICEKEY"

///>>>PARAMETERSNEEDTOBECHANGEDIFYOUCALLADIFFERENTFLOWCONTROL(LOGIN
METHOD)

/**

*@varstringcallbackUrl

*/

staticstringcallbackUrl="[Link]

/**

*Thefollowingmethodissuesarequestandreturnstheentireresponseasonelongstring

*/

publicstaticstringHttpGet(stringrequestUrl)

try

HttpWebRequestrequest=[Link](requestUrl)asHttpWebRequest

using(HttpWebResponseresponse=[Link]()asHttpWebResponse)

if([Link]!=[Link])

thrownewException([Link](

"Servererror(HTTP{0}:{1}).",

[Link],

[Link]))

stringresult=null

StreamReaderreader=newStreamReader([Link]())

result=[Link]()

returnresult

catch(Exceptione)

SvenskeidentitetABSvartbcksgatan5
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
Page(13/14)

[Link]([Link])

returnnull

/**

*getLoginurl

*/

publicstringLoginRequest()

//IssuetherequesttotheGrandidRestService

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

/**

*GetProfileinformationforthecurrentuser

*/

publicstringGetUserProfile(stringgrandidsession)

//IssuetherequesttotheGrandidRestService

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

}
}

SvenskeidentitetABSvartbcksgatan5
[Link]:556776699275320Uppsala

Tel:+46184811900
[Link]
Page(14/14)

You might also like