API Scopes and Access Control
Machine to Machine interaction from a client platform to the Fenergo SaaS APIs is secured using the Client Credential Grant Type. One of the parameters passed in the Authentication Request Body is the Scope Parameter. In essence, this parameter is asking the Authentication service to create an access token which has specific permissions. The Fenergo SaaS platform provides a granular way for clients to generate access tokens which only have the permission they need to perform the specific function they are intended for. This approach to security is better known as the System of Least Privilege and you can learn more about it API Security and Best Practice.
Requesting an Access Token with a specific Scope
If you have built an integration which needs to READ Legal Entity Data, perhaps as a reaction to to an event such as the completion of a Journey, the call to the identity provider for an access token should request only those permissions needed. This integration (at least for this specific use case) would not need the ability to create new legal entity data so the scope should only be fenx.entitydata.read. If there was also a need to get some data about the journey itself, then the integration would also need fenx.journey.read. Look at the console captured from a Postman session where we can see the Request Headers and the Request Body. The Scope parameter contains both required scopes (space separated). The resultant access token will not work for requests against any other APIs than those listed.
Request Headers
Content-Type: application/x-www-form-urlencoded
User-Agent: PostmanRuntime/7.29.0
Accept: *
Cache-Control: no-cache
Postman-Token: ace71fe5-84e7-44f9-95ce-9c147c147036
Host: identity.fenergox.com
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 136
Request Body
grant_type: "client_credentials"
scope: "fenx.entitydata.read fenx.journey.read"
client_id: "YOUR CLIENT ID"
client_secret: "YOUR CLIENT SECRET"
Currently there is a 300 character limit when specifying scopes as part of a token request. Decide on the level of granularity required per client credential with this in mind.
Fenergo have not yet moved to a level of granularity at a method level. So .read scopes are aligned to the Query APIs and .write scopes are aligned to the Command APIs
read more on scopes here: https://auth0.com/docs/get-started/apis/scopes
Full List of Available Scopes
Name | Display Name | Description |
|---|---|---|
| fenx.agents.read | Fen-X AI Agents API Read | Gives read access to AI Agent models |
| fenx.agents.write | Fen-X AI Agents API Write | Gives write access to AI Agent models |
| fenx.association.read | Fen-X Association API Read | Gives read access to Associations |
| fenx.association.write | Fen-X Association API Write | Gives write access to Associations |
| fenx.authorization.read | Fen-X Authorization API Read | Gives read access to Authorization |
| fenx.authorization.write | Fen-X Authorization API Write | Gives write access to Authorization |
| fenx.changemanagement.read | Fen-X Change Management API Read | Gives read access to Change Management |
| fenx.changemanagement.write | Fen-X Change Management API Write | Gives write access to Change Management |
| fenx.comments | Fen-X Comments GraphQL API | Gives full access to Comments GraphQL API |
| fenx.creditassessment.read | Fen-X Credit Assessment API Read | Gives read access to Credit Assessment |
| fenx.creditassessment.write | Fen-X Credit Assessment API Write | Gives write access to Credit Assessment |
| fenx.creditscreening.read | Fen-X Credit Screening API Read | Gives read access to Credit Screening |
| fenx.creditscreening.write | Fen-X Credit Screening API Write | Gives write access to Credit Screening |
| fenx.dashboards.read | Fen-X Dashboards API Read | Gives read access to Dashboards |
| fenx.datamigration.read | Fen-X Data Migration API Read | Gives read access to Data Migration |
| fenx.datamigration.write | Fen-X Data Migration API Write | Gives write access to Data Migration |
| fenx.digitalidv.read | Fen-X DigitalId&V API Read | Gives read access to DigitalId |
| fenx.digitalidv.write | Fen-X DigitalId&V API Write | Gives write access to DigitalId&V |
| fenx.documents.read | Fen-X Documents API Read | Gives read access to Documents |
| fenx.documents.write | Fen-X Documents API Write | Gives write access to Documents |
| fenx.entitydata.read | Fen-X Entity Data API Read | Gives read access to Entity Data |
| fenx.entitydata.write | Fen-X Entity Data API Write | Gives write access to Entity Data |
| fenx.etl.write | Fen-X ETL API Read and Write | Gives read and write access to ETL |
| fenx.eventingress | Fen-X Event Ingress API | Allows full access to Event Ingress API |
| fenx.eventnotifications | Fen-X Event Notifications API | Allows full access to Event Notifications API |
| fenx.externalauthentication.read | Fen-X External Authentication API Read | Gives read access to External Authentication |
| fenx.externalauthentication.write | Fen-X External Authentication API Write | Gives write access to External Authentication |
| fenx.externaldata.read | Fen-X ExternalData API Read | Gives read access to ExternalData |
| fenx.externaldata.write | Fen-X ExternalData API Write | Gives write access to ExternalData |
| fenx.financialanalysis.read | Fen-X Financial Analysis API Read | Gives read access to Financial Analysis |
| fenx.financialanalysis.write | Fen-X Financial Analysis API Write | Gives write access to Financial Analysis |
| fenx.journey.read | Fen-X Journey API Read | Gives read access to Journey |
| fenx.journey.write | Fen-X Journey API Write | Gives write access to Journey |
| fenx.localisation.read | Fen-X Localisation API Read | Gives read access to Localisation |
| fenx.localisation.write | Fen-X Localisation API Write | Gives write access to Localisation |
| fenx.lookup.read | Fen-X Lookup API Read | Gives read access to Lookup |
| fenx.lookup.write | Fen-X Lookup API Write | Gives write access to Lookup |
| fenx.outreach.read | Fen-X Outreach API Read | Gives read access to Outreach |
| fenx.outreach.write | Fen-X Outreach API Write | Gives writes access to Outreach |
| fenx.policy.read | Fen-X Policy API Read | Gives read access to Policy |
| fenx.policy.write | Fen-X Policy API Write | Gives write access to Policy |
| fenx.policyexternaladapter.read | Fen-X Policy External Adapter API Read | Gives read access to Policy External Adapter |
| fenx.policyexternaladapter.write | Fen-X Policy External Adapter API Write | Gives write access to Policy External Adapter |
| fenx.portal-tenant.read | Fen-X Portal Tenant API Write | Gives read access to Portal Tenant |
| fenx.portal-tenant.write | Fen-X Portal Tenant API Read | Gives write access to Portal Tenant |
| fenx.product.read | Fen-X Product API Read | Gives read access to Product |
| fenx.product.write | Fen-X Product API Write | Gives write access to Product |
| fenx.reporting.read | Fen-X Reporting API Read | Gives read access to Reporting |
| fenx.reports.read | Fen-X Advanced Reporting API Read | Gives read access to Advanced Reporting |
| fenx.reports.write | Fen-X Advanced Reporting API Write | Gives writes access to Advanced Reporting |
| fenx.risk.read | Fen-X Risk API Read | Gives read access to Risk models and perform calculations |
| fenx.risk.write | Fen-X Risk API Write | Gives writes access to Risk models |
| fenx.screening.read | Fen-X Screening API Read | Gives read access to Screening |
| fenx.screening.write | Fen-X Screening API Write | Gives write access to Screening |
| fenx.smartdocs.read | Fen-X Smartdocs API Read | Gives read access to IDP models |
| fenx.smartdocs.write | Fen-X Smartdocs API Write | Gives write access to IDP models |
| fenx.tenant.read | Fen-X Tenant API Read | Gives read access to Tenant |
| fenx.tenant.write | Fen-X Tenant API Write | Gives write access to Tenant |
| fenx.transferagency.write | Fen-X TransferAgency API Write | Gives write access to Transfer Agency |
| fenx.transferagency.read | Fen-X TransferAgency API Read | Gives read access to Transfer Agency |
| fenx.businessmetrics.write | Fen-X Business Metrics API Write | Gives write access to Business Metrics |
| fenx.businessmetrics.read | Fen-X Business Metrics API Read | Gives read access to Business Metrics |
| fenx.webhooks | Webhooks management API | Allows full access to Webhooks Management API |
| fenx.all | Fen-X All APIs | Gives full access to all Fen-X APIs |