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://apis.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://apis.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://apis.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