Authorization Code Grant Flow

Use the OAuth2 authorization code grant flow when a FieldAgent user is present and your application needs to access data on that user's behalf. Before using this flow, request an API integration and provide the redirect URI for your application.

The sequence diagram below illustrates the authorization code grant flow:

sequenceDiagram
    autonumber
    actor Browser
    Browser->>+Client App:Click Login with FieldAgent button
    Client App-->>-Browser:Redirect...
    Browser->>+FieldAgent Authentication:...to FieldAgent Login
    FieldAgent Authentication-->>-Browser:Returns FieldAgent Login form
    Browser->>+FieldAgent Authentication:Submit FieldAgent credentials
    Note right of FieldAgent Authentication:authenticate user
    FieldAgent Authentication-->>-Browser:Returns approve/deny access form
    Browser->>+FieldAgent Authentication:Submit approval
    FieldAgent Authentication-->>-Browser:Redirect...
    Browser->>+Client App:...with code
    Client App->>+FieldAgent Authentication:Request access token
    Note right of Client App:request includes:
grant type='authorization_code', 
client id, client secret,
code & redirect URI
    Note right of FieldAgent Authentication:validate:
client id, client secret & code
    FieldAgent Authentication-->>Client App:Returns access token & refresh token
    Client App->>+FieldAgent GraphQL API:Request user's fields
    Note right of Client App:request includes:
access token
    Note left of FieldAgent GraphQL API:validate:
access token
    FieldAgent GraphQL API-->>-Client App:Returns user's fields
    Client App-->>-Browser:Returns user's fields

If you prefer to just dive into some code and get going, there is a working code example that demonstrates this flow available at GitHub.

Requesting the Grant

The flow starts by making a request to the /oauth/authorize endpoint in FieldAgent and providing the required information as query string parameters.

To try this yourself, open a browser window and enter the following URL, replacing the stand-in values with actual values:

https://api.sentera.com/oauth/authorize?client_id=XXXX&response_type=code&redirect_uri=YYYY&scope=ZZZZ

XXXX is the client ID you received when you registered your client application with Sentera.
YYYY is the callback URI you provided when you registered your client application with Sentera.
ZZZZ is the scope you provided when you registered your client application with Sentera.

The values you supply must match the values registered for your application, or your request will be rejected.

Once you log into FieldAgent and grant access to your application, FieldAgent redirects the browser to your callback URI with the authorization code in the code query string parameter. Your application exchanges this short-lived code for tokens in the next step.

Getting an Access Token

Use the /oauth/token endpoint in FieldAgent to exchange the authorization code for an access token.

curl -i --request POST \
  --header 'Content-Type: application/json' \
  --data '{ "grant_type": "authorization_code", "client_id": "XXXX", "client_secret": "YYYY", "redirect_uri": "ZZZZ", "code": "CCCC" }' \
  https://api.sentera.com/oauth/token

XXXX is the client ID you received when you registered your client application with Sentera.
YYYY is the client secret you received when you registered your client application with Sentera.
ZZZZ is your application's registered callback URI.
CCCC is the authorization code returned to your callback URI.

Example response

{
  "access_token": "AeLRx-np4pdGRJWezDp8mh-VyqQD-yopEkbfLqmqNwg",
  "token_type": "Bearer",
  "expires_in": 28800,
  "refresh_token": "68OCxLVGMGcIMoHBvbHh0avldx9VAOcFNbekQMtI8Vw",
  "scope": "read_fields",
  "created_at": 1691152104
}

Calling the GraphQL API

Send the access token as a bearer token in the Authorization header:

curl --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: ******' \
  --data '{ "query": "query fields { fields { total_count } }" }' \
  https://api.sentera.com/graphql

AAAA is the access token returned by /oauth/token.

Refreshing an Access Token

Authorization-code access tokens expire after eight hours. Use the /oauth/token endpoint and the refresh token to obtain a new access token without asking the user to sign in again.

curl -i --request POST \
  --header 'Content-Type: application/json' \
  --data '{ "grant_type": "refresh_token", "client_id": "XXXX", "client_secret": "YYYY", "redirect_uri": "ZZZZ", "refresh_token": "RRRR" }' \
  https://api.sentera.com/oauth/token

XXXX is your client ID.
YYYY is your client secret.
ZZZZ is your registered callback URI.
RRRR is the refresh token returned with the previous access token.

Store the new access token and refresh token returned by this request.

Revoking Access

Use /oauth/revoke to revoke an access token or refresh token:

curl -i --request POST \
  --header 'Content-Type: application/json' \
  --data '{ "token_type_hint": "access_token", "client_id": "XXXX", "client_secret": "YYYY", "token": "AAAA" }' \
  https://api.sentera.com/oauth/revoke

To revoke a refresh token, set token_type_hint to refresh_token and provide the refresh token as token. Revoking a refresh token prevents it from being used to obtain more access tokens.

Return to Authentication overview.