Password Credential Login

The Password Credential Login flow allows a client to use userid/password credentials to get an access token. The following is an overview diagram for Accela OAuth2 Resource Owner Password Credentials flow.

To get an access token using the Password Credentials login flow:

1. Get your app ID and app secret values

   Log in 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 from Accela Developer Portal > My Apps.

2. Get an access token

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

   • HTTP method: POST

   • HTTP content type: application/x-www-form-urlencoded

   Request Parameters:

   Parameter	Type	Description
   client_id	Required	The app ID value from Accela Developer Portal > My Apps.
   client_secret	Required	The app secret value from Accela Developer Portal > My Apps.
   grant_type	Required	The grant type of the current request. The value must be set to "password". Note: Make sure the grant_type value "password" does not contain any space character.
   username	Required	For a citizen app, the user name is the Civic ID. For an agency app, the user name is the Accela Automation account.
   password	Required	The corresponding password of the Civic ID or Accela Automation account.
   scope	Required	The value of the scope parameter is expressed as a list of space-delimited, case-sensitive strings. The strings are defined by the authorization server. If the value contains multiple space-delimited strings, their order does not matter, and each string adds an additional access range to the requested scope. For example, "create_record get_record" indicates a requested scope which shows the access range of creating a record and getting a record.
   agency_name	Optional/Required	The agency identifier as registered within the Construct admin portal. APIs such as Get All Agencies, Get Agency and Search Agencies return valid agency names. For a citizen app, agency_name is optional. For an agency app, agency_name is required.
   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.

   HTTP Response:

   HTTP content type: application/json

   Parameter	Type	Description
   access_token	Required	The issued access token containing the agency, environment, user and scopes. Subsequent API calls will only require an Authorization header using this token.
   token_type	Required	The type of the issued token. It contains the fixed value "bearer" for current 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/Required	Required if the "state" parameter was present in the client authorization request. Indicates the exact value received from the client.

   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/ Required	Required if "state" parameter was present in the client authorization request. 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/token
   HTTP Method	POST
   HTTP Header	Content-Type: application/x-www-form-urlencoded
   HTTP Body	grant_type=password &client_id=634922733084115102 &client_secret=abb1e0eca03e4ccaaf9b67955c48c01c &username=developer &password=accela &scope= get_records &agency_name=Nullisland &environment=TEST

   Sample Response

   HTTP Body

   { "access_token": "3xGDezCgbB3BC4eAb4llKWfxiM0pnTGXzpUR61aSNP2frS8 T3zOnUR3jxZeN08Xzn-5RCJ7XJzD02X3ZP8Pq2z_Hp_0IpQKtIy0d4g8nva XTyNc1IUKD4uNO92KlQ1Q-O5Ds782a0zB6jfxmpvpnfMMnm7Vn8Be6hP txJvOdGnpW9tjPr5O3CnNdJfMnyhk79eyRiNmDO6ePjMN2HQxPAbl3FKl QKb3KXXN2qJHgJJR_pt91ZKfckqn-i2OjmKSZThzFFigpDbG7avQc4r2jAn VuqDbwEbNQBUDEVD8vyXPgIB5_w-tS1oY_mTeYyC8szwY2C-47YoCO -D9gCxsf0-Z9jcsxYYeaHKzOZivv82_nGHqE9kvq1WuCAbqTM06E4a49EX a4xmStdmuHMG789uDbfvsO8axCh9ELUA8XE8REzcVhh0Ri7KPAHABYx uhWuRnTStA39qnhFJu71CVClBSWo-n4ri2CYRQMgGhVa9Up4X9oGSPHa Il76cAnzLwRNnJpYOoTkK0fMwdVpGLThN_y7zjqbzmipcin0POO-C6gTS_ mFeJ8dD8IBFtPHkxPeojEHZwQwzKIhAPQb0vjLp6n5MT0Y6t-PHSlpmaUY 1MC7vTFaQCH0Nvn-QvCJa2Nw0ZY0p3MLfrEjFOSFsTuqOEhXQLbd8Eakg 3HSXiTvUIC9cnJMBk9-rkd9_1bapYWOosYJsj4Mqy_23QgNgSTyMI4QVV dGJgWgYOSchN_QfzlBF4ymL8C0zSB1NfX-MmXoLOHl-Sh-2gJblBhnPj08 dywe6n6XHm-sar2t_RJnZDgwD4h95BTlJq91NcZOVJtkPNVDM7KPmddzV I3uyboWBpCcZOmRokJhBCEST8mueJKqmmjzAjPxCSYdBD4Zj7g4G_gp0l CKFr3nO7-UgGwCXfyAnWpcb0uTfv5usCfwcwdatXv6nCOH_qTQtbEeWfx0", "token_type": "bearer", "expires_in": "28800", "refresh_token": "OvNl!IAAAAGbyAM37pxFdYBt4JOtavTO2M2cm30mDjmhe IchHAcvagQIAAAHwT4HFP0bRLmFq7WncMnySLkg08yxYDelCoKcqcdw6iK VVUE2pG8TS91pCxerJRLTpzmFQZqsIsC1G0yRBoU1_hfYkZfkz4QHoUQcPs XjzR_xrr8mF_5d0VcY8RsF1uTLkvu-YHwcmaG-yphtkNFpAhMOuXF26TiYgH F0w53o-u8FlP8NnSqAFkSSNYn64rqarvp1LVTF4dMaoWjMr1XvmVlaIFBoHS R_Df4qCZMd-rDY3g9txDhJYKlOhNCv8AhooI3nde7ogJaj9siFhyZbbKEQyd5t5 0cicvZlbfLn-fgaUig4CdWufUCwC4YqsSt0aGmrhP4R40VWUNOaQFA3-6pNdO MEqdMckgWf5dAd2uy1HDU91Dy37sC2eOYk7c3MRhS_oI4ejjBEo5E7wnjrO6 hj24E-Wy3SyZqdWgCX7BPxX_DLHlA_WaiwmId8jIb1qTuKeOeguKtAz0 _9QpxyOcjDtmmBKv2jQMEhpDtob1Cy8HHr2vuydiSPVeJbAHDp8Hb_Q11 UdqBrgq0Bgi9khHdpBFvggbUwNeG6HLt3e3SrCEIOm0BWuJ2kKhIA4Vxug L9ZjB5tW78vjaseVhpQfkQNL56fnCft6GLSwYuzqPaKMRDIIYdzireG8GJ4bm 4S_4U7Vxpys_bfaN4MVmawk8uJkAzmlTfORFGiWAv_ydRT1mYL9YoYjY8Je KzdmGqDd6KQNcmOKHnZgPTn31JlFowqO-EqceHoRrjgcXRjDCqn9A dfp0Ub_ERkM_2U0sNmkgbkiY0pH4vmPPXUoPtpntdgxR12-DoJj-wm XJjO_QpIl6zk36jo41m_i2B5vWLZK8rRWvAalwrrC5BRapBA", "scope": "get_records" }

3. Refresh an access tokens (optional)

   If an access token expires, use the following API to refresh the access token.

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

   • HTTP method: POST

   • HTTP content type: application/x-www-form-urlencoded

   Request Parameters:

   Parameter	Type	Description
   client_id	Required	The app ID value from Accela Developer Portal > My Apps.
   client_secret	Required	The app secret value from Accela Developer Portal > My Apps.
   grant_type	Required	The 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 Response:

   HTTP content type: application/json

   Response Data:

   Parameter	Type	Description
   access_token	Required	The user access token.
   token_type	Required	The type of the issued token. It contains the fixed value "bearer" for current 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/Required	The exact value received from the client. Required if the "state" parameter was present in the client authorization request.

   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/ Required	The exact state value received from the client request. Required if "state" parameter was present in the client authorization 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/token
   HTTP Method	POST
   HTTP Header	Content-Type: application/x-www-form-urlencoded
   HTTP Body	grant_type=refresh_token &client_id=634922733084115102 &client_secret= abb1e0eca03e4ccaaf9b67955c48c01c &refresh_token=AQNb!IAAAAG_3b0qMrBi7gGRdIbB3dH5uAs0pb3GvM6f2Fwkl WxBOAQEAAAGHqoZ1BACTzLa8hkNLqgVpN1TalKG2kaadzAdr1i1osrLWxFT caJH_0OghkVyJnDqwwpKbDaFtB5VzdZNdKd_u1CMXOJwjqX1ZjplqidDRYi0aE hUP_m8C_OyVdcKZsLvp0pWwcx9vmM4ApceYpS5SKLORyToxL920D8oONkQ SEAk_aqNlg0D7v-Cjx8ja8dESkkdnMNQwZ_APU4xhUwjJ3bB64n739SCLIDynpmH ahFPcWXMuMsbythf8oYIOKZS8ip7y3Xe39b4lhvNTPxzs-tRwojVIFyB6d_ h5e1DMfH3WnPp_L-54Zjb5Zo9kzjsgzbNN3es0MDcdru35AyGg

   Response:

   HTTP Body

   { "access_token": "3xGDezCgbB3BC4eAb4llKWfxiM0pnTGXzpUR61aSNP2frS8 T3zOnUR3jxZeN08Xzn-5RCJ7XJzD02X3ZP8Pq2z_Hp_0IpQKtIy0d4g8nva XTyNc1IUKD4uNO92KlQ1Q-O5Ds782a0zB6jfxmpvpnfMMnm7Vn8Be6hP txJvOdGnpW9tjPr5O3CnNdJfMnyhk79eyRiNmDO6ePjMN2HQxPAbl3FKl QKb3KXXN2qJHgJJR_pt91ZKfckqn-i2OjmKSZThzFFigpDbG7avQc4r2jAn VuqDbwEbNQBUDEVD8vyXPgIB5_w-tS1oY_mTeYyC8szwY2C-47YoCO -D9gCxsf0-Z9jcsxYYeaHKzOZivv82_nGHqE9kvq1WuCAbqTM06E4a49EX a4xmStdmuHMG789uDbfvsO8axCh9ELUA8XE8REzcVhh0Ri7KPAHABYx uhWuRnTStA39qnhFJu71CVClBSWo-n4ri2CYRQMgGhVa9Up4X9oGSPHa Il76cAnzLwRNnJpYOoTkK0fMwdVpGLThN_y7zjqbzmipcin0POO-C6gTS_ mFeJ8dD8IBFtPHkxPeojEHZwQwzKIhAPQb0vjLp6n5MT0Y6t-PHSlpmaUY 1MC7vTFaQCH0Nvn-QvCJa2Nw0ZY0p3MLfrEjFOSFsTuqOEhXQLbd8Eakg 3HSXiTvUIC9cnJMBk9-rkd9_1bapYWOosYJsj4Mqy_23QgNgSTyMI4QVV dGJgWgYOSchN_QfzlBF4ymL8C0zSB1NfX-MmXoLOHl-Sh-2gJblBhnPj08 dywe6n6XHm-sar2t_RJnZDgwD4h95BTlJq91NcZOVJtkPNVDM7KPmddzV I3uyboWBpCcZOmRokJhBCEST8mueJKqmmjzAjPxCSYdBD4Zj7g4G_gp0l CKFr3nO7-UgGwCXfyAnWpcb0uTfv5usCfwcwdatXv6nCOH_qTQtbEeWfx0", "token_type": "bearer", "expires_in": "28800", "refresh_token": " AQNb!IAAAAFZ_yW-9MQxxWVzXTgLPEZhSZGgUc9BLF Hi63advYilBAQEAAAGFT1MoIDAplxRvez-KBB_qKtz13V8mtU6I6wF_vCPBue 422aozp3Ar8DaaFciv_fAnwGJ63SEmmB7_zps-sZfPf-RcvD9FGTDDQytnOhH2F yGEjnlDaYsWoSYw7fj52bTJO7KY8HDI7N9KwHHZo6oss3wWY3APe-eUXf5O P53OSM3VZ_M5ij-kHDlPDTV7e30HOcdoGj76Pns3hxRSGTd9dtw4mPOOSeAH wy6mDeS6uqH9bcBHD9zSqOm16iwbXlayfEWH8xh3LTdMgcxAoKcCRZ-nChvxhtuk8BP3IbXvRP8KjXWl8TJ8NoJOtb1Q5R89ROPVt3xfsRHoihEAvV8Y ", "scope": "get_records" }

4. 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.
   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.
   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"
   }

5. Invoke APIs using the 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/v4/records
   HTTP Method	GET
   HTTP Headers	Content-Type: application/json Accept: application/json x-accela-appid: 634922733084115102 Authorization: 3xGDezCgbB3BC4eAb4llKWfxiM0pnTGXzpUR61aSNP2frS8 T3zOnUR3jxZeN08Xzn-5RCJ7XJzD02X3ZP8Pq2z_Hp_0IpQKtIy0d4g8nva XTyNc1IUKD4uNO92KlQ1Q-O5Ds782a0zB6jfxmpvpnfMMnm7Vn8Be6hP txJvOdGnpW9tjPr5O3CnNdJfMnyhk79eyRiNmDO6ePjMN2HQxPAbl3FKl QKb3KXXN2qJHgJJR_pt91ZKfckqn-i2OjmKSZThzFFigpDbG7avQc4r2jAn VuqDbwEbNQBUDEVD8vyXPgIB5_w-tS1oY_mTeYyC8szwY2C-47YoCO -D9gCxsf0-Z9jcsxYYeaHKzOZivv82_nGHqE9kvq1WuCAbqTM06E4a49EX a4xmStdmuHMG789uDbfvsO8axCh9ELUA8XE8REzcVhh0Ri7KPAHABYx uhWuRnTStA39qnhFJu71CVClBSWo-n4ri2CYRQMgGhVa9Up4X9oGSPHa Il76cAnzLwRNnJpYOoTkK0fMwdVpGLThN_y7zjqbzmipcin0POO-C6gTS_ mFeJ8dD8IBFtPHkxPeojEHZwQwzKIhAPQb0vjLp6n5MT0Y6t-PHSlpmaUY 1MC7vTFaQCH0Nvn-QvCJa2Nw0ZY0p3MLfrEjFOSFsTuqOEhXQLbd8Eakg 3HSXiTvUIC9cnJMBk9-rkd9_1bapYWOosYJsj4Mqy_23QgNgSTyMI4QVV dGJgWgYOSchN_QfzlBF4ymL8C0zSB1NfX-MmXoLOHl-Sh-2gJblBhnPj08 dywe6n6XHm-sar2t_RJnZDgwD4h95BTlJq91NcZOVJtkPNVDM7KPmddzV I3uyboWBpCcZOmRokJhBCEST8mueJKqmmjzAjPxCSYdBD4Zj7g4G_gp0l CKFr3nO7-UgGwCXfyAnWpcb0uTfv5usCfwcwdatXv6nCOH_qTQtbEeWfx0