Creating a JDBC Data Source

You can create a JDBC data source to connect from your Java application using the CData JDBC Driver for Linear.

Follow these steps:

1. Add the driver JAR file to the classpath. The JAR file is located in the installation directory's lib subfolder. Ensure that the .lic file is located in the same folder as the JAR file.
2. Provide the driver class. For example:
   

   cdata.jdbc.linear.LinearDriver

3. Provide the JDBC URL. For example:
   

   jdbc:linear:APIKey=myAPIKey;

   Or, if there is a conflict in your application between drivers using the same URL format, use this form to ensure that you are using the CData driver:
   

   jdbc:cdata:linear:APIKey=myAPIKey;

   Ensure that the URL starts with either jdbc:linear: or jdbc:cdata:linear:. The URL can include any of the connection properties in name-value pairs separated with semicolons.

Connecting to Linear

You can authenticate to Linear with a personal API key or with OAuth 2.0.

• API Key: The simplest option. Use it to connect with your own Linear account.
• OAuth (authorization code): Authenticate an application on behalf of a Linear user. Set AuthScheme to OAuth.
• OAuth (client credentials): Authenticate the application itself, for app-owned (machine-to-machine) access with no user interaction. Set AuthScheme to OAuthClient.

Authenticate with an API Key

To connect with a personal API key, set the following:

• AuthScheme: APIKey.
• APIKey: A Linear personal API key.

To create a personal API key:

1. Log in to Linear and open Settings > Security & access > Personal API keys.
2. Select New API key, name it, and create it.
3. Copy the key immediately. Linear shows it only once.

Authenticate with OAuth

The driver supports the OAuth 2.0 authorization code grant. All OAuth flows require a custom OAuth application registered in Linear.

See Creating a Custom OAuth Application for the steps to create one.

Client Credentials

Use the client credentials grant to authenticate the application itself, with no user sign-in. This is suited to backend or machine-to-machine integrations that act as the OAuth application rather than on behalf of a specific user.

Set the following and connect:

• AuthScheme: OAuthClient.
• OAuthClientId: The Client ID from your OAuth application.
• OAuthClientSecret: The Client Secret from your OAuth application.

Note: To request specific OAuth scopes, set Scope to a comma-separated list (for example, read,write). When omitted, the driver requests read,write. Scope is optional and is not a standard connection property.

No browser interaction or callback URL is required. The driver obtains an access token directly from the Linear token endpoint and refreshes it automatically.

Desktop Applications

After registering a custom OAuth application, set the following and connect:

• InitiateOAuth: GETANDREFRESH. Use InitiateOAuth to avoid repeating the OAuth exchange and manually setting the OAuthAccessToken.
• OAuthClientId: The Client ID from your OAuth application.
• OAuthClientSecret: The Client Secret from your OAuth application.
• CallbackURL: The Callback URL defined in your OAuth application (for example, http://localhost:33333).

Note: To request specific OAuth scopes, set Scope to a comma-separated list (for example, read,write). When omitted, the driver requests read,write. Scope is optional and is not a standard connection property.

When you connect, the driver opens Linear's OAuth endpoint in your default browser. Log in and grant access to the application. The driver then completes the OAuth process:

1. The driver obtains an access token from Linear and uses it to request data.
2. The OAuth values are saved in the location specified by OAuthSettingsLocation and persist across connections.

The driver refreshes the access token automatically when it expires.

Web Applications

To connect from a web application, use the driver to obtain and manage the OAuth token values.

Get an OAuth Access Token

Set the following connection properties:

• OAuthClientId: The Client ID from your OAuth application.
• OAuthClientSecret: The Client Secret from your OAuth application.

Then call stored procedures to complete the OAuth exchange:

1. Call the GetOAuthAuthorizationURL stored procedure. Set the CallbackURL to the redirect URI registered with your OAuth application. The procedure returns the URL to the Linear authorization endpoint.
2. Open the returned URL in a browser. Log in and authorize the application. Linear redirects to your callback URL with a code parameter appended.
3. Call the GetOAuthAccessToken stored procedure. Set the Verifier input to the code value from the redirect, and CallbackURL to the same redirect URI.

After you obtain the access and refresh tokens, set the following to connect and refresh the token automatically:

• InitiateOAuth: REFRESH.
• OAuthClientId: The Client ID from your OAuth application.
• OAuthClientSecret: The Client Secret from your OAuth application.
• OAuthAccessToken: The access token returned by GetOAuthAccessToken.
• OAuthSettingsLocation: A writable path where the driver persists the OAuth values across connections.

Headless Machines

To authenticate on a machine without a browser, obtain the OAuth values on another machine that has a browser and transfer them.

1. On a machine with a browser, register the custom OAuth application and complete a desktop or web flow to obtain an OAuthAccessToken and OAuthRefreshToken (or an OAuthVerifier).
2. On the headless machine, set InitiateOAuth to REFRESH, supply OAuthClientId, OAuthClientSecret, the token values, and OAuthSettingsLocation. The driver then refreshes the access token automatically.