Implicit Flow

The implicit grant type is used to obtain access tokens and is optimized for public clients known to operate a particular redirection URI. These clients are typically implemented in a browser using a scripting language such as JavaScript. The following diagram shows an overview of the implicit flow.

The sequence begins by redirecting a browser to an Accela Authentication Server URL with a set of query parameters. The Civic Platform handles the user authentication and user consent, and responds back with an access token. The application can access an Accela API after it receives the user access token. The flow does not support the issuance of refresh tokens.

To get access token using the implicit 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. Request access token

    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 by 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 "token".

    NOTE: For implicit login flow, make sure the response_type value is "token".

    client_id Required The app ID value from Accela Developer Portal.
    redirect_uri Optional

    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 the 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 utilize 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: do 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 Construct 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 some unique value. This can be used for CSRF protection.

    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=token
  2. Redirect user to the login dialog

    If the end users have not logged in during access token request, 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 an access token and other result data.

    The login Dialogs for Citizen Apps and Agency Apps displays the login dialogs for Accela citizen and agency apps.

  3. Get access token in redirect URL

    HTTP Response

    If the resource owner grants the access request, the authorization server issues an access token and delivers it to the client by adding the following parameters to the fragment component of the redirection URI using the "application/x-www-form-urlencoded" format.

    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.
    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.
    scope Optional The scope of the resources authenticated by the authorization server.
    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.

    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.

    Response Sample

    URL
    http://MyServer/LoginResponse#access_token=UZgs!IAAAAMxBrPKyPkReA9c439-ED2UlAUINyz286KXUf1I4bNy0QIAAAGP1Dds68ynOulQ2ZGs0dKgOfLNshNtTXZazcZvmW-S4ocq7RZrBSdbHfNUOtst7kqQxZ6MO3cLwVHem52KzjzgPSM3HnDmbPLX_
     &token_type=bearer
     &expires_in=86400
     &environment=PROD
     &agency_name=NULLISLAND
     &scope=get_records%20get_record%20search_records
     &state= abcxyz123
  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. 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://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 access token

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

    Request Sample

    URL https://apis.accela.com/v4/civicid/profile
    HTTP Method GET
    HTTP Header
    Content-Type: application/json 
     Accept: application/json
    Authorization:3xGDezCgbB3BC4eAb4llKWfxiM0pnTGXzpUR61aSNP2frS8T3zOnU
     R3jxZeN08Xzn-5RCJ7XJzD02X3ZP8Pq2z_Hp_0IpQKtIy0d4g8nvaXTyNc1IUKD4uNO92KlQ1Q
     -O5Ds782a0zB6jfxmpvpnfMMnm7Vn8Be6hPCKFr3nO7gGwCXfyAnWpcb0uTfv5usC
     fwcwdatXv6nCOH_qTQtbEeWfx0