Skip to main content
System StatusContact Support
VersionOne Community

Creating a Connection

Connecting to the VersionOne API via the Java SDK involves determining the URL of your VersionOne instance, determining the API authentication type that you want use, determining your proxy credentials (if you use one), and then building a connection object. To build a connection object you'll use the V1Connector object which is implemented using a fluent builder interface.

Here's an example of how to use the V1Connector with an access token:

V1Connector connector = V1Connector
    .withInstanceUrl("<Server Base URI>")
    .withUserAgentHeader("AppName", "1.0")
    .withAccessToken("1.rWM8lKLk+PnyFxkEWVX5Kl2u6Jk=")
    .build();

A few things to point out abut the V1Connector:

  • The Server Base URI is the URL that you use for your VersionOne instance and is typically in the form of "http(s)://server name/instance name".
  • The user agent header is used to pass the name and version number of your application to the API which can help with log analysis should there be an issue.
  • The build method is the builder's terminating method and returns the V1Connector object which you will then pass to other objects when performing actions with the API.

The V1Connector is a new connector released with the 15.0.0.0 version of the Java SDK, and it replaces the legacy V1APIConnector. The legacy connector is still available for use within the SDK but has been marked for deprecation. It will be removed in a future release.

Connecting with Basic Authentication

When using Basic authentication, you use the withUsernameAndPassword method, passing in the username and password of the VersionOne member account that you want to connect with:

V1Connector connector = V1Connector
    .withInstanceUrl("<Server Base URI>")
    .withUserAgentHeader("AppName", "1.0")
    .withUsernameAndPassword("username", "password")
    .build();

Connecting with Windows Integrated Authentication

When using Windows Integrated Authentication, you use the withWindowsIntegrated method. If you want to use the SDK with the currently logged in user's account, you do not need to pass any parameters:

V1Connector connector = V1Connector
    .withInstanceUrl("<Server Base URI>")
    .withUserAgentHeader("AppName", "1.0")
    .withWindowsIntegrated()
    .build();

Unlike the .NET SDK, the Java SDK does not support using Windows Integrated Authentication with specific user credentials, you can only use the credentials of the currently logged in user.

Connecting with Access Tokens

When using Access Token Authentication, you use the withAccessToken method, passing in the access token associated with the VersionOne member account that you want to connect with:

V1Connector connector = V1Connector
    .withInstanceUrl("<Server Base URI>")
    .withUserAgentHeader("AppName", "1.0")
    .withAccessToken("1.rWM8lKLk+PnyFxkEWVX5Kl2u6Jk=")
    .build();

When trying to use an access token when your VersionOne instance has been configured to use Windows Integrated Authentication, you will need to use the special useOAuthEndpoints method of the connector. This method allows the connector to bypass NTLM and authenticate directly to the API with an access token.

V1Connector connector = V1Connector
    .withInstanceUrl("<Server Base URI>")
    .withUserAgentHeader("AppName", "1.0")
    .withAccessToken("1.rWM8lKLk+PnyFxkEWVX5Kl2u6Jk=")
    .useOAuthEndpoints()
    .build();

Connecting with OAuth2 Tokens

As of Winter 2016 release notes our intent is to sunset OAuth2 in favor of Access Tokens. 

When using OAuth2 Authentication, you use the withOAuth2Token method, passing in the OAuth2 access token associated with the VersionOne member account that you want to connect with:

V1Connector connector = V1Connector
    .withInstanceUrl("<Server Base URI>")
    .withUserAgentHeader("AppName", "1.0")
    .withOAuth2Token("AAEAAJa0PvSSjkBYffqqU2f5oPCFLimIhiiQaiM04VO-5p7Nmlm0W9bqM59...")
    .build();

The Java SDK only supports connecting with a valid OAuth2 access token, it does not do the full authorization of the token, nor does it refresh the token. If you wish to use OAuth2 as your authentication method, you may want to use a third-party library like Apache OLTU or the Google OAuth Client Library to assist with generating and refreshing your OAuth2 access tokens.

Connecting with a Proxy

If you are using a proxy in your environment, you can use the withProxy method, passing in a ProxyProvider object hydrated with the URL, username, and password used to authenticate with the proxy:

ProxyProvider proxyProvider = new ProxyProvider(new URI("proxyURL"), "proxyUsername", "proxyPassword");

V1Connector connector = V1Connector
    .withInstanceUrl("<Server Base URI>")
    .withUserAgentHeader("AppName", "1.0")
    .withAccessToken("1.rWM8lKLk+PnyFxkEWVX5Kl2u6Jk=")
    .withProxy(proxyProvider)
    .build();

You cannot use a proxy when connecting with Windows Integrated Authentication.

  • Was this article helpful?