The objects available within our connector are accessible from the "cdata.linear" module. To use the module's objects directly:

1. Import the module as follows:
   

   import cdata.linear as mod

2. To establish a connection string, call the connect() method from the connector object using an appropriate connection string, such as:
   

   mod.connect("APIKey=myAPIKey;")

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 connector 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 connector requests read,write. Scope is optional and is not a standard connection property.

No browser interaction or callback URL is required. The connector 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 connector requests read,write. Scope is optional and is not a standard connection property.

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

1. The connector 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 connector refreshes the access token automatically when it expires.

Web Applications

To connect from a web application, use the connector 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 connector 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 connector then refreshes the access token automatically.