Overview
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.
Note
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.
Current Options
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.
Future Options
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 | Agility | Access Token |
| On-Premise | Windows Integrated Authentication | Access Token |
| On-Demand | Agility | Access Token |
| On-Demand | SSO | Access Token |
Single Sign-On authentication considerations
On-Premise
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.
On-Demand
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.
Comments
Please sign in to leave a comment.