Depending upon where your Agility instance is installed and how it's configured, there are special considerations for accessing the REST API. In most of the documentation, you'll see the rest-1.v1 endpoint referenced in examples. You may instead need to use rest-1.oauth.v1 under certain conditions.
Currently, if your instance is configured with Windows Integrated Authentication Mode and you want your code to use Access Tokens, you will need to use a slight variation named rest-1.oauth.v1.
We will remove the rest-1.oauth.v1 endpoint in a future release. When we do this, we will change rest-1.v1 to work only with Access Tokens.
This table summarizes the current options:
|Installation Type||Authentication Mode||rest-1.v1 supports:||rest-1.oauth.v1 supports:|
|On-Premise||Agility||Access Token||Access Token|
|On-Premise||Windows Integrated Authentication||Windows Integrated Authentication (for capable clients)||Access Token|
|On-Demand||Agility||Access Token||Access Token|
|On-Demand||SSO||Not Available||Access Token|
Basic Auth Information
You may currently use Basic Auth (username/password) anywhere the table shows Access Token above with the exceptions of an On-Premise instance configured in Windows Integrated Authentication Mode and an On-Demand SSO instance. But, like the rest-1.oauth.v1 endpoint, this capability will be removed in a future release. Thus, we recommend transitioning to Access Tokens now.
As mentioned above, we will remove rest-1.oauth.v1 and Basic Auth completely in a future release. The following table summarizes what the options will look like at that time:
|Installation Type||Authentication Mode||rest-1.v1 supports:|
|On-Premise||Windows Integrated Authentication||Access Token|
Single Sign-On authentication considerations
If you are using On-Premise Single-Sign-On authentication (SSO), you must configure your SSO provider's rules to either allow or deny rest-1.v1 and/or rest-1.oauth.v1. We recommend just exposing rest-1.v1, because rest-1.oauth.v1 will eventually be removed.
If you are using On-Demand Single Sign-On, then your code must authenticate with an Access Token. We recommend coding against the rest-1.v1 endpoint, because rest-1.ouath.v1 will eventually be removed. See Agility On-Demand Single Sign-On for more information.