Authorization Code Flow

The authorization code is obtained by using an authorization server as an intermediary between the client and resource owner. Instead of requesting authorization directly from the resource owner, the client directs the resource owner to an authorization server, which in turn directs the resource owner back to the client with the authorization code. The following diagram shows an overview for Accela OAuth2 authorization code flow.

The sequence begins by redirecting a browser to an Accela URL with a set of query parameters. The authorization server 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 a Accela API after it receives the user access token.

Before or when the access token expires, the app can refresh the access token.

To get access token using the authorization code flow

Note: The line breaks shown in the sample request and response URLs in the following steps are only to make these better readable. Delete the line breaks for your actual use.

  1. 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-agent (e.g. browser).

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

    • HTTP method: GET or POST

    Request Parameters

    Parameter Type Description
    response_type Required The grant type that the client requests. The value must be set to "code".
    client_id Required The app ID value from Accela Developer Portal.
    redirect_uri Required

    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 The Accela environment name, such as "PROD" and "TEST". The Get All Agency Environments API returns a list of configured environments available for a specific agency. The Get Environment Status checks connectivity with the Agency/Environment.
    agency_name Optional The agency name defined in Accela Administrator Portal. APIs such as Get All Agencies, Get Agency and Search Agencies return valid agency names. The agency name is required in the majority of cases. It is optional only for citizen apps that use dynamic agency routing functionality.
    forcelogin Optional

    Indicates whether or not Accela Auth server forces end-user login each time client requests access token.

    true: always force end-user login

    false: not force end-user login. The sever determines if the current request needs login. This is the default behavior.
    scope Optional

    The scope of the resources that the client requests. Enter a list of APIs scope names separated by spaces. Alternatively, instead of using a long list of scope names, use the scope group. You get scope names from the Accela API Reference.

    Note that your app cannot use APIs beyond what is requested here while obtaining the token.
    state Optional An opaque value that the client uses for maintaining the state between the request and callback. Enter a unique value. This can be used for Cross-Site Request Forgery (CSRF) protection.
    Response Data
    Parameter Type Description
    code Required The authorization code. The client app uses the authorization code to exchange for an access token.
    environment Required

    The environment name that the user selected when signing into the app.
    agency_name Optional

    The agency name that the user entered when signing into the app.
    state Optional The exact value received from the client. Check this value against original state value sent in the request to verify and protect against CSRF.
    Error Response
    Parameter Type Description
    error Required The error code. Refer here for details.
    error_description Optional The error description text.
    error_uri Optional The URI of web page with more information about the error.
    state Optional The exact state value received from the client request.

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

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

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

  3. Exchange authorization code for access token.

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

    Content-Type: application/x-www-form-urlencoded

    x-accela-appid: YOUR_APP_ID
    Request Parameters
    Parameter Type Description
    client_id Required The app ID value from Accela Developer Portal.
    client_secret Required The app secret value from Accela Developer Portal.
    grant_type Required The authorization code grant type of the current request. The value must be set to "authorization_code".
    Note: Make sure the grant_type value "authorization_code" does not contain any space character.
    redirect_uri Required

    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

    The authorization code obtained in step 1.

    Note: 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.

    Note: The code can be used no more than one time, the client should apply the rule during exchange access token.
    state Optional 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 content type: application/json

    Response Data
    Parameter Type Description
    access_token Required The issued user access token.
    token_type Required The type of the token issued. It contains the fixed value "bearer" for authorization code grant type.
    expires_in Required 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 The refresh token that can be used to obtain a new access token.
    scope Optional The scope of the resources authenticated by the authorization server.
    state Optional The exact value received from the client.
    Request Sample
    HTTP Method POST
    URL https://auth.accela.com/oauth2/token
    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

    Response Sample (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"
}

  4. 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. Your app can refresh the token before it expires or when it expires, according your app requirements or workflow.

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

    Content-Type: application/x-www-form-urlencoded

    x-accela-appid: YOUR_APP_ID
    Request Parameters
    Parameter Type Description
    client_id Required The app ID value from Accela Developer Portal.
    client_secret Required The app secret value from Accela Developer Portal.
    grant_type Required The authorization code grant type of the current request. The value must be set to "refresh_token".
    refresh_token Required The refresh token value obtained in the prior access token API request.

    HTTP content type: application/json

    HTTP Response Data
    Parameter Type Description
    access_token Required The issued user access token.
    token_type Required The type of the token issued. It contains the fixed value "bearer" for the authorization code grant type.
    expires_in Required 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 The refresh token that can be used to obtain a new access token.
    scope Optional The scope of the resources authenticated by the authorization server.
    state Optional The exact value received from the client.
    Request Sample
    HTTP Method POST
    URL https://auth.accela.com/oauth2/token
    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

    Response Sample (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"
}

  5. Validate the token.

    It may be necessary to validate or get information about a token from the Accela Auth server to check whether it is the token requested by your client and generated for your client. To validate and match token information with the information used to request the access token, call the token validation API:

    • HTTP Request URI: https://auth.accela.com/oauth2/tokeninfo

    • HTTP method: GET

    • HTTP headers: Authorization: {access token}

    Response Data

    Parameter Description
    appId The app ID value from Accela Developer Portal. This value is passed in your access token request.
    userId The logged in user's unique id.
    agencyName The agency name defined in the Accela Administrator Portal. The agency name is passed by client request or chosen by the end-user during access token request flow. APIs such as Get All Agencies, Get Agency and Search Agencies return valid agency names.
    environment The Accela environment name, such as "PROD" and "TEST". The environment is passed by client request or chosen by the end-user during access token request flow. The Get All Agency Environments API returns a list of configured environments available for a specific agency. The Get Environment Status checks connectivity with the Agency/Environment.
    scopes The scopes of the resources that the client requests
    expiresIn The lifetime in seconds of the access token.
    Request Sample
    URL https://auth.accela.com/oauth2/tokeninfo
    HTTP Method GET
    HTTP Header 
    Authorization: 3xGDezCgbB3BC4eAb4llKWfxiM0pnTGXzpUR61aSNP2frS8T3zOnU
 R3jxZeN08Xzn-5RCJ7XJzD02X3ZP8Pq2z_Hp_0IpQKtIy0d4g8nvaXTyNc1IUKD4uNO92KlQ1Q
 -O5Ds782a0zB6jfxmpvpnfMMnm7Vn8Be6hPCKFr3nO7gGwCXfyAnWpcb0uTfv5usC
 fwcwdatXv6nCOH_qTQtbEeWfx0

    Response Sample 

    {
 "appId": "123450949800276721",
 "userId": "63e79004",
 "agencyName": "myAgency",
 "environment": "DEV",
 "scopes": [
    "addresses",
    "agencies",
    "get_civicid_profile",
    "records",
    "settings"
 ],
 "expiresIn": 85158
}

    Error Response Sample

    If the token has expired or has been invalidated, the Accela Auth server returns an error with a 400 status, as shown below: 

    {
    "status": 400,
    "code": "invalid_token",
    "message": "Invalid token.",
    "traceId": "140530084954807-61409b20"
}

  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.

    Request Sample

    HTTP Method GET
    URL https://apis.accela.com/v3/system/common/modules
    HTTP Header

    Content-Type: application/json

    Accept: application/json

    x-accela-appid: 634922733084115102
    Authorization 
    3xGDezCgbB3BC4eAb4llKWfxiM0pnTGXzpUR61aSNP2frS8T3
 zOnUR3jxZeN08Xzn-5RCJ7XJzD02X3ZP8Pq2z_Hp_0IpQKtIy0d4g8nvaXTyNc1
 IUKD4uNO92KlQ1Q-O5Ds782a0zB6jfxmpvpnfMMnm7Vn8Be6hPCKFr3nO7
 gGwCXfyAnWpcb0uTfv5usCfwcwdatXv6nCOH_qTQtbEeWfx0