Skip to main content

Tenant Access

In order to start working with the Fenergo SaaS platform APIs you will first need access to a tenant. Fenergo will set these up for you and give you the different Tenant Ids.

info

Not all Tenants will be set up at the same time, Provisioning your production tenant will likely be done last as most clients elect to use BYOK and this step needs to be completed by clients first.

Request Your Client Credential​

Once your Tenant is provisioned, the next step to making API calls is request your Client Credential. This is the recommended method for calling APIs on the Fenergo SaaS platform. It can be requested to be configured with pre-determined scopes. Scope control is used to control what the credential has access to in terms of APIs. Click Here to learn more about API Scopes. It is recommended to facilitate development in lower SDLC tenants and then use more granular scope control in production. This adheres to the Principal of Least Privilege.

Client Credentials as Super Users

The Access Layers and field level data permissions which work for User Interface Users DO NOT apply to the client credential grant type.For example, If a client credential has been allocated access to fenx.entitydata.read then it will be able to READ all Entity Data. It will not be restricted based on access layers.

Best Practice for API Access

It is standard best practice to use the Client Credential Grant Type to build integrations and system to system interactions. It is NOT recommended to use a user account for accessing APIs. Doing so would require not only storing but managing the username and password to ensure the integration works correctly (including adhering to password rotation).

Authenticating​

You do not need to use your Tenant Id when using the Client Credential to request an ACCESS TOKEN. You simply need to make the ACCESS TOKEN request against the token endpoint available for the Region you have selected for your tenants. Likely to be named something like https://identity.{regionname}.fenergox.com/connect/token. The RAW request body for an access token is below.

Request Body for an Access Token
Request Body
    client_secret: "xxxxxxx-XXX-XXXX-XXXX-xxxxxxxxxx"
    scope: "fenx.all"
    grant_type: "client_credentials"
    client_id: "client-id-for-your-tenant"

The Response Body will be as below inluding the ACCESS TOKEN.

Response Body including Access Token
Response Body
{
    "access_token": "XXXXXXXXXXXXXXXXXXX",
    "expires_in": 900,
    "token_type": "Bearer",
    "scope": "fenx.all"
}
Expiry Time and Bearer Status

The Token has a TTL (time to live) of 900 seconds (15 minutes) and will not be accepted after that time expires. This is also a Bearer token, so will be accepted from whomever presents it. Clients are encouraged to cache and reuse their ACCESS TOKENS for the full TTL as the Authentication Endpoint which issues the tokens is throttled to 100 requests per minute from a single IP Address Source.

API Request Requirements​

All API calls need to contain:

  • The URL endpoint for the API call which cna be retrieved from the API Documentation.
  • Appropriate URL Parameters where required
  • The correctly formatted JSON Request Body where required.
  • HTTP Header x-tenant-id specifying the Tenant Id.
  • HTTP Header Authorization which should contain the Access Token in the format: Bearer: {access-token}

See the below raw HTTP Request headers (replace the tenant-id and Authorization with actual values.)

Request Headers
x-tenant-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxx
Authorization: Bearer XXXXXXXXXXXXXXXXXXX
User-Agent: PostmanRuntime/7.37.0
Accept: */*
Host: api.fenergox.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive