Accela Login - Getting Started

Accela Login - Getting Started

iOS SDK
Android SDK
Windows 8 SDK

Introduction

Accela offers multiple login flows to suit for different app development scenarios using OAuth 2.0 standard.

The login flow generates an access token, which you can use to make API calls on behalf of a user. Accela client SDK handles access token generation, persistence, signing of API calls automatically.

Server-side login flow may be used in cases where use of client side SDK is not appropriate or you want to develop an app in a language where SDK is not yet available.

Accela iOS SDK installer package provides SDK and Xcode templates to quickly create iOS apps. SDK provides mechanism for user login, getting tokens, using tokens to interact with APIs and logging off users. When you create your app using the Xcode template, the code for login function is generated automatically.

Important steps using Accela iOS SDK

1) Initialize SDK

The following code snippet demonstrates how to initialize an Accela iOS instance.

2) Invoke user login dialogs and receive access token

The following code demonstrates how to launch Accela login dialogs. Once a user logs in and authorizes the app, the app will receive the user access token.

You can replace the following permission scopes with those described at Accela API Reference.

3) Interact with APIs

The following code snippet demonstrates how to call an API to get a list of records, and defines a request delegate to handle the returned response asynchronously.

4) Log off

The following code snippet demonstrates how to log off the current user.

Refer to Getting Started guide for more information about using Accela iOS SDK.

Login with Android SDK

Accela Android SDK plug-in for Eclipse provides SDK and Eclipse project templates to quickly create Android apps. SDK provides mechanism for user login, getting tokens, using tokens to interact with APIs and logging off users. When you create your app using the Eclipse project template, the code for login function is generated automatically.

Important steps using Accela Android SDK

1) Declare the "AuthorizationActivity" activity

The following code snippet demonstrates how to declare the "AuthorizationActivity" activity in the AndroidManifest.xml file.

2) Initialize SDK

The following code snippet demonstrates how to initialize an AccelaMobile instance. The app ID and app secret are defined in the <project_root>\assets\accela.properties file.

<project_root> represents the root directory of the current project.

3) Invoke user login dialogs and receive access token

The following code snippet demonstrates how to launch an Accela login view through a web browser, and defines a session delegate to handle the authorization result asynchronously.

Once a user logs in successfully, the amDidLogin() method in this session delegate will be called back.

You can replace the following permission scopes with those described at Accela API Reference.

4) Interact with APIs

The following code snippet demonstrates how to call an API to get a list of inspections, and defines a request delegate to handle the returned response asynchronously.

Once the valid JSON is returned, the onSuccess() method in this request delegate will be called back.

5) Log off

The following code snippet demonstrates how to log off the current user.

Once the logout() method is called, the amDidLogout() method in the predefined session delegate will be called back automatically.

Login with Windows 8 SDK

Accela Windows 8 SDK plug-in for Visual Studio provides SDK and Visual Studio project templates to quickly create Windows Store Apps. SDK provides mechanism for user login, getting tokens, using tokens to interact with APIs and logging off users. When you create your app using the Visual Studio project template, the code for login function is generated automatically.

Important steps using Accela Windows 8 SDK

1) Initialize SDK

The following code snippet demonstrates how to initialize an Accela SDK instance with the parameter values entered in the project wizard of Accela SDK Plug-in (for Visual Studio 2012).

2) Invoke user login dialogs and receive access tokens

The following code snippet demonstrates how to launch an Accela login view through a web browser, and defines a session delegate to handle the authorization result asynchronously.

Once a user logs in successfully, the SessionChanged() method in this session delegate will be called back.

You can replace the following permission scopes with those described at Accela API Reference.

3) Interact with APIs

The following code snippet demonstrates how to call an API to get a list of records, and defines a request delegate to handle the returned response asynchronously.

4) Log off

The following code snippet logs off the current user.

Server-side Login

Server-side login flow may be used in cases where use of client side SDK is not appropriate or you want to develop an app in a language where SDK is not yet available. The following is an overview diagram for Accela OAuth2 authorization code flow.

The sequence begins by redirecting a browser to an Accela URL with a set of query parameters. The Civic Apps Platform handles the user authentication and user consent, and responds back with an authorization code. After receiving the authorization code, the application can exchange the code for an access token and a refresh token. The application can access an Accela API after it receives the user access token.

The following are the steps in getting access token using the server-side login flow.

1) Get your app ID and app secret values

Login to Accela Developer portal and create an agency or citizen app. Once an app is created, note down the app ID and app secret values.

2) Get authorization code

The app constructs the request URI by adding the following parameters to the query or form component of the authorization endpoint URI using the "application/x-www-form-urlencoded" format, and sends the request URI via user-agen (e.g. browser).

HTTP Request URITP Request URI: https://auth.accela.com/oauth2/authorize

HTTP method: GET or POST

Request Parameters:

Parameter	Type	Description
response_type	Required	Indicates the grant type that the client requests. The value must be set to "code".
client_id	Required	Enter your app ID value from Accela Developer portal.
redirect_uri	Required	Indicates the URI that the authorization server redirects back to the client with an authorization code. This must be a valid URL. Note: special characters in the Url should be encoded.
environment	Required	Indicates the Accela environment name, such as "PROD" and "TEST", for more information, please contact agency administrator.
agency_name	Optional	Indicates the agency name defined in the Admin portal. The agency name is required in the majority of cases. It is optional only for citizen apps that utilize dynamic agency routing functionality, for more information, please contact agency administrator.
scope	Optional	Indicates the scope of the resources that the client requests. Enter a list of APIs scope names separated by spaces. You may get these names at Accela API Reference. Note that your app cannot use APIs beyond what is requested here while obtaining the token.
state	Optional	Indicates an opaque value that the client uses for maintaining the state between the request and callback. Enter some unique value. This can be used for Cross-Site Request Forgery (CSRF) protection.

Response Data:

Parameter	Type	Description
code	Required	Indicates the authorization code. The client app uses this authorization code to exchange for an access token.
environment	Required	Indicates the environment name. Indicates the environment name that the user selected when signing into the app.
agency_name	Optional	Indicates the agency name. Indicates the agency name that the user entered when signing into the app.
state	Optional	Indicates the exact value received from the client. Check this value against original state value sent in the request to verify and protect against Cross-Site Request Forgery (CSRF).

Error Response:

Parameter	Type	Description
error	Required	Indicates the error code. Refer here for details.
error_description	Optional	Indicates error description text.
error_uri	Optional	Indicates the URI of web page with more information about the error.
state	Optional	Indicates the exact state value received from the client request.

Sample Request:

Note: The line breaks shown below in URLs are only to make these better readable. Delete the line breaks for your actual use.

URL	https://auth.accela.com/oauth2/authorize?client_id=63492273279 &agency_name=ISLANDTON &environment=PROD &redirect_uri=http%3a%2f%2fMyServer%2fLoginResponse &state=abcxyz123 &scope=get_records%20get_record%20search_records &response_type=code
HTTP Method	GET

Sample Response:

URL

http://MyServer/LoginResponse?code=UZgs!IAAAAMxBrPKyPkReA9c439-ED2UlAUINyz286KXUf1I4bNy0QIAAAGP1Dds68ynOulQ2ZGs0dKgOfLNshNtTXZazcZvmW-S4ocq7RZrBSdbHfNUOtst7kqQxZ6MO3cLwVHem52KzjzgPSM3HnDmbPLX_
&agency_name=ISLANDTON
&environment=PROD
&state= abcxyz123

3) Redirect user to the login dialog

If the end-users have not logged in, they will be redirected to the citizen or agency login dialog based on the app type (citizen app or agency app). After login, they will be redirected to a page where they need to authorize the app. After they authorize the app, it will be redirected back to redirect_uri with the authorization code value.

The following are login dialogs for Accela citizen and agency apps.

Citizen app login dialog

Agency app login dialog

4) Exchange authorization code for access token

HTTP Request URI: https://apis.accela.com/oauth2/token
HTTP method: POST

HTTP Headers:
Content-Type: application/x-www-form-urlencoded
x-accela-appid: YOUR_APP_ID

Request Parameters:

Parameter	Type	Description
client_id	Required	Enter your app ID value from Accela Developer portal.
client_secret	Required	Enter app secret value from Accela Developer portal.
grant_type	Required	Indicates the authorization code grant type of the current request. The value must be set to "authorization_code".
redirect_uri	Required	Indicates the URI that is used to redirect to the client with an access token. Note: If the "redirect_uri" parameter was included in the previous authorization request, then the same value should be included here.
code	Required	Enter the authorization code obtained in the previous step. Note: a. the code should be URL-encoded, if you are using tools or libraries which will auto-encode the code, you need to pass the code under decoded. b. the code can be used no more than once, the client should apply the rule during exchange access token.
state	Optional	Indicates an opaque value that the client uses for maintaining the state between the request and callback. Enter some unique value. This can be used for CSRF protection.

HTTP Response

HTTP content type: application/json

Response Data:

Parameter	Type	Description
access_token	Required	Indicates the user access token.
token_type	Required	Indicates the type of the token issued. It contains the fixed value "bearer" for authorization code grant type.
expires_in	Required	Indicates the lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
refresh_token	Required	Indicates the refresh token that can be used to obtain a new access token.
scope	Optional	Indicates the scope of the resources authenticated by the authorization server.
state	Optional	Indicates the exact value received from the client.

Sample Request:

The line breaks shown below is to make this request better readable. You should delete the line breaks for your actual use.

URL	https://apis.accela.com/oauth2/token
HTTP Method	POST
HTTP Header	Content-Type: application/x-www-form-urlencoded x-accela-appid: 634922454502
HTTP Body	grant_type=authorization_code &client_id=634922454502 &client_secret=abb1e067955c48c01c &redirect_uri= http%3a%2f%2fMyServer%2fLoginResponse &code=UZgs!IAAAAMxBrPKyPkReA9c439-ED2UlAUINyz286KXUf1I4bNy-0QI AAAGP1Dds68ynOulQ2ZGs0dKgOfLNshNtTXZazcZvmW-S4ocq7RWJHbMpd kz1rAEfL6QoFjsIKbVspqrgrwNcka53tsrBpveD6yIMVjyyD8R37xtiZhaXen &state=abcxyz123

Sample Response:

HTTP Body

{

"access_token": "3xGDezCgbB3BC4eAb4llKWfxiM0pnTGXzpUR61aSNP2frS8

T3zOnUR3jxZeN08Xzn-5RCJ7XJzD02X3ZP8Pq2z_Hp_0IpQKtIy0d4g8nvaXTyN

c1IUKD4uNO92KlQ1Q-O5Ds782a0zB6jfxmpvpnfMMnm7Vn8Be6hPCKFr3nO7

-UgGwCXfyAnWpcb0uTfv5usCfwcwdatXv6nCOH_qTQtbEeWfx0",

"token_type": "bearer",

"expires_in": "28800",

"refresh_token": "OvNl!IAAAAGbyAM37pxFdYBt4JOtavTO2M2cm30mDjmhe

IchHAcvagQIAAAHwT4HFP0bRLmFq7WncMnySLkg08yxYDelCoKcqcdw6iK

VVUE2pG8TS91pCxerJRLTpzmFQZqsIsC1G0yRBoU1_hfYkZfkz4QHoUQcPs

dfp0Ub_ERkM_2U0sNmkgbkiY0pH4vmPPXUoPtpntdgxR12-DoJj-wmXJjO_Qp

Il6zk36jo41m_i2B5vWLZK8rRWvAalwrrC5BRapBA",

"scope": "get_records get_record search_records"

}

5) Refresh the Access Token (Optional)

Access tokens have a limited lifetime and, in some cases, an application needs access to an API beyond the lifetime of a single access token. When this is the case, your application can obtain a new access token using the refresh token.

HTTP Request URI:https://apis.accela.com/oauth2/token

HTTP method: POST

HTTP Headers:
Content-Type: application/x-www-form-urlencoded
x-accela-appid: YOUR_APP_ID

Request Parameters:

Parameter	Type	Description
client_id	Required	Enter your app ID value from Accela Developer portal.
client_secret	Required	Enter your app secret value from Accela Developer portal.
grant_type	Required	Indicates the authorization code grant type of the current request. The value must be set to "refresh_token".
refresh_token	Required	Enter the refresh token value obtained in the prior access token API request.

HTTP Response:

HTTP content type: application/json

Response Data:

Parameter	Type	Description
access_token	Required	Indicates the user access token.
token_type	Required	Indicates the type of the token issued. It contains the fixed value "bearer" for the authorization code grant type.
expires_in	Required	Indicates the lifetime in seconds of the access token. For example, the value "3600" denotes that the access token will expire in one hour from the time the response was generated.
refresh_token	Required	Indicates the refresh token that can be used to obtain a new access token.
scope	Optional	Indicates the scope of the resources authenticated by the authorization server.
state	Optional	Indicates the exact value received from the client.

Sample Request:

URL	https://apis.accela.com/oauth2/token
HTTP Method	POST
HTTP Header	Content-Type: application/x-www-form-urlencoded x-accela-appid: 634922755554115102
HTTP Body	grant_type= refresh_token &client_id=634922755554115102 &client_secret= abb1e0e9b67955c48c01c &refresh_token=AQNb!IAAAAG_3b0qMrBi7gGRdIbB3dH5uAs0pb3GvM6f2Fwkl WxBOAQEAAAGHqoZ1BACTzLa8hkNLqgVpN1TalKG2kaadzAdr1i1osrLWxFT h5e1DMfH3WnPp_L-54Zjb5Zo9kzjsgzbNN3es0MDcdru35AyGg

Sample Response:

HTTP Body

{

"access_token": "3xGDezCgbB3BC4eAb4llKWfxiM0pnTGXzpUR61aSNP2frS8

T3zOnUR3jxZeN08Xzn-5RCJ7XJzD02X3ZP8Pq2z_Hp_0IpQKtIy0d4g8nvaXTyN

c1IUKD4uNO92KlQ1Q-O5Ds782a0zB6jfxmpvpnfMMnm7Vn8Be6hPtxJvOdGnp

W9tjPr5O3CnNdJfMnyhk79eyRiNmDO6ePjMN2HQxPAbl3FKl

"token_type": "bearer",

"expires_in": "28800",

"refresh_token": " AQNb!IAAAAFZ_yW-9MQxxWVzXTgLPEZhSZGgUc9BLFH

i63advYilBAQEAAAGFT1MoIDAplxRvez-KBB_qKtz13V8mtU6I6wF_vCPBue422

aozp3Ar8DaaFciv_fAnwGJ63SEmmB7_zps-sZfPf-RcvD9FGTDDQytnOhH2F

"scope": "get_records get_record seach_records"

}

6) Invoke APIs using user access token

After getting an access token, assign the value of the token to the "Authorization" header to invoke APIs.

Sample Request:

URL

https://apis.accela.com/v3/system/common/modules

HTTP Method

GET

HTTP Header

Content-Type: application/json

Accept: application/json

x-accela-appid: 634922733084115102

Authorization:3xGDezCgbB3BC4eAb4llKWfxiM0pnTGXzpUR61aSNP2frS8T3

zOnUR3jxZeN08Xzn-5RCJ7XJzD02X3ZP8Pq2z_Hp_0IpQKtIy0d4g8nvaXTyNc1

IUKD4uNO92KlQ1Q-O5Ds782a0zB6jfxmpvpnfMMnm7Vn8Be6hPCKFr3nO7

gGwCXfyAnWpcb0uTfv5usCfwcwdatXv6nCOH_qTQtbEeWfx0

Accela Login - Getting Started

Introduction

Login with iOS SDK

Login with Android SDK

Login with Windows 8 SDK

Server-side Login