Access Token Authentication
Starting October 19, 2022, you can connect your corporate identity provider to using the Platform's Identity service. Once connected, Platform will act as an identity broker between your IdP (Identity Provider) and , allowing your users to securely access all products and the support, documentation, and community portals using the same credentials they use throughout your enterprise.
If you have not yet migrated your single sign-on (SSO) and user management to the Platform and want to do so, write to support@digital.ai for assistance.
If you have any further questions, please reach out to your contact or write to support@digital.ai.
Overview
Digital.ai Agility Access Tokens provide a secure and streamlined approach for authenticating with the Digital.ai Agility API. They are more secure than Basic Authentication. Access Tokens can be used for API access no matter what authentication method your Digital.ai Agility instance is configured to use, including SAML SSO.
Key advantages of using Digital.ai Agility Access Tokens include:
-
Easy to create and revoke
-
Managed by the member that created them and administrators
-
Simple to pass in the authorization header of an HTTP request
-
Never expire or have to be refreshed
-
Works with all types of Digital.ai Agility authentication configurations including Basic (username and password), Windows Integrated Authentication (NTLM), and SAML SSO
Creating Access Tokens
Applications that access the Digital.ai Agility API using Access Tokens must be created as an application within Digital.ai Agility. Applications may be created in the following ways:
- Administrators: System Admins can create Public applications in the Administration Applications screen, and Personal applications in their Member Applications page, or through the API using the Application asset.
- Members: Members can create Personal applications in the Member Applications page, or through the API using the Application asset.
Once a Public or Personal application has been created, administrators and members can then create a grant for those applications using the Access Token authentication type. The grant allows an application to operate on the member's behalf with the same Roles and Project Memberships that are assigned to that member.
While applications may be created through the API, grants may not. You must use the Digital.ai Agility user interface to create grants for applications.
Using Access Tokens
Once an Access Token has been created, you can use that Access Token for all calls to the Digital.ai Agility API. Access Tokens are passed as"Bearer" tokens in the Authorization header of a HTTP request. Unlike when making a request using Basic Authentication, Access Tokens do not require any special type of encoding since they have already been encoded.
Here's an example of how to use an Access Token in the Authorization header of a HTTP request:
GET /v1sdktesting/rest-1.v1/Data/Scope/0 HTTP/1.1 Host: www14.v1host.com
Authorization: Bearer 1.vlog8vBO7ZZQZQD7ZSTtO++Ez8Y=
Revoking Access Tokens
While grants and their associated Access Tokens cannot be created with the API, they can be revoked through the API, or through the Digital.ai Agility user interface.
Revoking a grant through the API is accomplished by issuing a "Revoke" operation on the grant by executing a HTTP POST request like the following:
POST /v1sdktesting/rest-1.v1/Data/Grant/1020?op=Revoke HTTP/1.1 Host: www14.v1host.com
Authorization: Bearer 1.vlog8vBO7ZZQZQD7ZSTtO++Ez8Y=
Only System Admins and the member that created the Access Token grant may revoke it.