VersionOne Access Tokens provide a secure and streamlined approach for authenticating with the VersionOne API. They are more secure than Basic Authentication. Access Tokens can be used for API access no matter what authentication method your VersionOne instance is configured to use, including SAML SSO.
Key advantages of using VersionOne 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 VersionOne authentication configurations including Basic (username and password), Windows Integrated Authentication (NTLM), and SAML SSO
Creating Access Tokens
Applications that access the VersionOne API using Access Tokens must be created as an application within VersionOne. 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 VersionOne 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 VersionOne 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 VersionOne 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.