Client Credentials Grant Flow

Use the OAuth2 client credentials grant flow for an unattended server-to-server integration where no FieldAgent user is present to sign in or approve access. Before using this flow, request an API integration. Sentera will associate the OAuth application with a dedicated FieldAgent integration user and provide a client ID and client secret.

Do not use this flow in browser-based, mobile, desktop, or other public clients that cannot keep a client secret confidential. Use the authorization code grant flow when a FieldAgent user is present.

The sequence diagram below illustrates the client credentials grant flow:

sequenceDiagram
    autonumber
    participant Service as Client Service
    participant Authentication as FieldAgent Authentication
    participant API as FieldAgent GraphQL API
    Service->>+Authentication:Request access token
    Note right of Service:request includes:
grant type='client_credentials',
client id & client secret
    Note right of Authentication:validate:
client id & client secret
    Authentication-->>-Service:Returns access token
    Service->>+API:Send GraphQL request
    Note right of Service:request includes:
access token
    Note left of API:validate:
access token & application owner
    API-->>-Service:Returns requested data

Getting an Access Token

Send your application credentials to the /oauth/token endpoint:

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

XXXX is the client ID Sentera provided for your server-to-server application.
YYYY is the client secret Sentera provided for your server-to-server application.

Keep the client secret in a secure server-side secrets store. Do not place it in source control, logs, browser code, mobile applications, or other locations accessible to end users.

Example response

{
  "access_token": "AeLRx-np4pdGRJWezDp8mh-VyqQD-yopEkbfLqmqNwg",
  "token_type": "Bearer",
  "expires_in": 1800,
  "scope": "read_fields",
  "created_at": 1691152104
}

Client-credentials access tokens expire after 30 minutes. This flow does not issue a refresh token.

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. API access is evaluated using the dedicated FieldAgent integration user associated with the OAuth application.

Renewing Access

Request a new access token from /oauth/token before or after the current token expires. Use the same client_credentials request shown above. Your service should cache and reuse an unexpired token rather than requesting a new token for every GraphQL operation.

If a token request or API call returns an authentication error, do not repeatedly retry with the same rejected credentials. Confirm that the client ID and client secret are current, then contact Sentera if the problem persists.

Revoking an Access Token

Use /oauth/revoke when an access token should no longer be usable:

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

Revoking one access token does not invalidate the application's client credentials. If the client secret is exposed or compromised, stop using it and contact Sentera so the credentials can be rotated.

Return to Authentication overview.