Authentication Options for gsqlcmd

/accessToken=<token>

Use this option to set an OAuth1/OAuth2 access token.

You can specify the OAuth2 token type using the /tokenType option. The default value is "Bearer".

For example:

/accessToken=12345 /tokenType=Bearer

/accessTokenUrl=<URL>

Use this option to set the OAuth1 service-specific URL for obtaining an access token.

/auth=Auto | None | Basic | Windows | Forms | OAuth1 | OAuth2 | Custom

Use this option to define the authentication method: Auto, None, Basic, Windows, Forms, OAuth1, OAuth2, or Custom.

For example:

gsqlcmd download https://localhost/crm/contacts /auth=Forms /username=user /password=pass

You can also omit the authentication method and specify only the username and password:

gsqlcmd download https://localhost/crm/contacts /username=user /password=pass

In this case, gsqlcmd will attempt to detect the appropriate method automatically.

To enforce the two-phase OAuth1 method, specify the /consumerKey and /consumerSecret options like this:

gsqlcmd download https://website.com/api/get-quotes /consumerKey=app /consumerSecret=appSecret

You can authorize the request interactively using the /interactive option:

gsqlcmd download https://localhost/crm/contacts /interactive

/authCode=<code>

This option is a synonym for the /code option.

/authorizationHeader=<value>

Use this option to specify the authorization header for a custom authentication provider.

For example:

"/authorizationHeader=Bearer 12345"

This is equivalent to:

"/header=Authorization: Bearer 12345"

/authUri=<URL>

This option is a synonym for the /authorizationUrl option.

It loads authorization URLs from client configuration files, such as those exported from Google.

/authorizationUrlFormat=<URL format>

Use this option to customize the format of an OAuth2 authorization URL.

The default value is:

{authorization_url}?scope={scope}&client_id={client_id}&response_type={response_type}&redirect_uri={redirect_uri}

/authorizationUrl=<URL>

Use this option to specify an OAuth1/OAuth2 authorization URL or the root URL of a web service using Forms authentication.

For example:

/authorizationUrl=https://accounts.google.com/o/oauth2/auth

gsqlcmd can usually detect Forms authentication root URLs successfully, so set this option if Forms authentication fails.

/callback=<URI>

Use this option to specify the callback URI for the registered OAuth1 application.

For example:

/callback=https://www.gsqlcmd.com/

/clientId=<clientId>

Use this option to set the clientId value for the registered OAuth2 application.

For example:

gsqlcmd download https://website.com/api/get-quotes /clientId=myapp /clientSecret=mypassword

gsqlcmd will use this value for OAuth1 authentication if the /consumerKey option is not specified.

/clientJson=<filename>

Use this option to specify a file containing client credentials and required authentication information.

For example:

gsqlcmd get-token /clientJson=client_secret.json /tokenJson=access_token.json ^
                  /scope=https://www.googleapis.com/auth/webmasters.readonly

Services often allow exporting such files from registered application pages.

For example, a Google Search Console client secret file looks like this:

{"installed":{
    "client_id":"123456789012-abcdefghijklmnopqrstuvwxyz123456.apps.googleusercontent.com",
    "project_id":"searchconsoleapi-123456",
    "auth_uri":"https://accounts.google.com/o/oauth2/auth",
    "token_uri":"https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url":"https://www.googleapis.com/oauth2/v1/certs",
    "client_secret":"Abcdefghijklmnopqrstuvwx",
    "redirect_uris":["urn:ietf:wg:oauth:2.0:oob","http://localhost"]
}}

If you prepare such files manually, you can split settings using the /clientJson and /serviceJson options.

You can also use plain text instead of JSON. For example, the settings shown above can be represented as:

client_id=123456789012-abcdefghijklmnopqrstuvwxyz123456.apps.googleusercontent.com
project_id=searchconsoleapi-123456
auth_uri=https://accounts.google.com/o/oauth2/auth
token_uri=https://oauth2.googleapis.com/token
auth_provider_x509_cert_url=https://www.googleapis.com/oauth2/v1/certs
client_secret=Abcdefghijklmnopqrstuvwx
redirect_uris=urn:ietf:wg:oauth:2.0:oob,http://localhost

/clientSecret=<clientSecret>

Use this option to set the clientSecret value for the OAuth2 authentication scheme.

For example:

gsqlcmd download https://website.com/api/get-quotes /clientId=myapp /clientSecret=mypassword

gsqlcmd will also use this value for OAuth1 authentication if the /consumerSecret option is not specified.

/code=<code>

Use this option to set an OAuth2 authorization code obtained from a browser, allowing you to skip acquiring the code using the built-in gsqlcmd browser.

For example:

/code=12345

/consumerKey=<consumerKey>

Use this option to set the consumerKey value for the registered OAuth1 application.

For example:

gsqlcmd download https://website.com/api/get-quotes /consumerKey=app /consumerSecret=appSecret

/consumerSecret=<consumerSecret>

Use this option to set the consumerSecret value for the registered OAuth1 application.

For example:

gsqlcmd download https://website.com/api/get-quotes /consumerKey=app /consumerSecret=appSecret

/cookie=<cookie>

Use this option to set a cookie for Forms or Custom authentication methods.

For example:

gsqlcmd download https://website.com/api/get-quotes /cookie=.ASPXFORMSAUTH=D3A...

You can also use the /cookieFile option to define the cookie in a file instead of as an inline parameter.

/cookieFile=<filename>

Use this option to specify a file containing a cookie for Forms or Custom authentication methods.

For example:

gsqlcmd download https://website.com/api/get-quotes /cookieFile=cookie.txt

The cookie file should contain only the cookie value. For example:

.ASPXFORMSAUTH=D3A...

gsqlcmd updates the cookie file when the service returns an updated cookie.

To prevent updating the cookie file, use the /options option instead. For example:

gsqlcmd download https://website.com/api/get-quotes /options=options.txt

In this case, you need to name the value in the file. The sample options.txt should look like this:

cookie=.ASPXFORMSAUTH=D3A...

/expiresIn=<seconds>

Use this option to set the token expiration time in seconds.

For example:

/expiresIn=3600

gsqlcmd uses this value to refresh expired tokens automatically based on the date and time in the file specified with the /tokenJson option.

Typically, you won't need to set this manually, as the exported token file contains this value.

The /validTo option takes precedence.

/grantType=<type>

Use this option to specify the required grant type.

For example:

/grantType=authorization_code

OAuth2 defines the following types: authorization_code, client_credentials, password, and refresh_token.

However, OAuth2 allows for extended types as well, so refer to the service documentation.

/getTokenBodyFormat=<body format>

Use this option to customize the body of an OAuth2 token request.

The default value is:

grant_type={grant_type}&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}&code={code}

/getTokenUrl=<URL>

Use this option to set the URL for an OAuth2 token request.

gsqlcmd uses the /token_uri value by default if this option is not specified.

/getTokenUrlFormat=<URL format>

Use this option to customize the URL for an OAuth2 token request.

The default value is:

{get_token_url}

/interactive[=true | false]

Use this option to enable interactive authorization for the request.

For example:

gsqlcmd download https://localhost/crm/contacts /interactive

This mode does not require additional parameters for Basic, Windows, and Forms authentication schemes.

For OAuth1, OAuth2, or Custom authentication schemes, specify the required client and service settings:

gsqlcmd download https://localhost/crm/contacts /interactive /clientJson=client.txt /serviceJson=service.txt /tokenJson=token.json

/oauthExpiresIn=<seconds>

Use this option to set the OAuth1 access token expiration time in seconds.

Typically, you won't need to set this manually, as the exported token file contains this value.

gsqlcmd uses this value to refresh expired tokens automatically based on the date and time in the file specified with the /tokenJson option.

The /validTo option takes precedence.

/oauthSessionHandle=<value>

Use this option to set an OAuth1 session handle value.

Typically, you won't need to set this manually, as the exported token file contains this value.

/oauthToken=<token>

Use this option to set an OAuth1 access token.

Typically, you won't need to set this manually, as the exported token file contains this value.

/oauthTokenSecret=<token secret>

Use this option to set an OAuth1 access token secret.

Typically, you won't need to set this manually, as the exported token file contains this value.

/password=<password>

Use this option to set a password for web resources protected by Basic, Windows, or Forms authentication schemes.

For example:

gsqlcmd download https://localhost/crm/contacts /auth=Forms /username=user /password=pass

/redirectUri=<URI>

Use this option to specify the redirect URI for the registered OAuth2 application.

For example:

/redirectUri=urn:ietf:wg:oauth:2.0:oob

gsqlcmd also uses this value as the default for OAuth1 authentication if the /callback option is not set.

/redirectUris=<URI>

This option is a synonym for the /redirectUri option, used to import URIs from files specified with the /clientJson option.

/refreshToken=<token>

Use this option to set an OAuth2 refresh token for updating an expired access token.

For example:

/refreshToken=1/ABCDEFGHIJKLMNOPQRST-abcdefghijklmnopqrstuv

Typically, you won't need to set this manually, as the exported token file contains this value.

/refreshTokenBodyFormat=<body format>

Use this option to customize the body of an OAuth2 refresh token request.

The default value is:

refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type={grant_type}

/refreshTokenUrl=<URL>

Use this option to set the URL for an OAuth2 refresh token request.

gsqlcmd uses the /token_uri value by default if this option is not specified.

/refreshTokenUrlFormat=<URL format>

Use this option to customize the URL for an OAuth2 refresh token request.

The default value is:

{refresh_token_url}

/requestTokenUrl=<URL>

Use this option to set an OAuth1 service-specific URL for requesting a token.

/responseType=<type>

Use this option to specify an OAuth2 response type.

For example:

/responseType=code

OAuth2 defines two response types: code and token.

However, OAuth2 allows services to define extended types as well, so refer to the service documentation.

/revokeTokenBodyFormat=<body format>

Use this option to customize the body of an OAuth2 revoking token request.

The default value is:

token={refresh_token}

/revokeTokenUrl=<URL>

Use this option to set the URL for an OAuth2 revoking token request.

/revokeTokenUrlFormat=<URL format>

Use this option to customize the URL for an OAuth2 revoking token request.

The default value is:

{revoke_token_url}

/scope=<scope>

Use this option to specify the required scope for an OAuth2 authentication scheme.

Find the scopes in the target service API documentation.

For example, for Google Search Console:

gsqlcmd get-token /clientJson=client_secret.json /tokenJson=access_token.json ^
                  /scope=https://www.googleapis.com/auth/webmasters.readonly

/serviceJson=<filename>

Use this option to specify a file containing service options instead of inline values.

For example:

gsqlcmd ... /clientJson=client.json /serviceJson=service.json /tokenJson=token.json ...

Services may allow exporting client and service settings in a single file, often used with the /clientJson option.

This option is useful for separating client and service options if you prepare the files manually.

You can use either JSON or plain text format.

Below is a suggested content for the service.txt file for Zoho CRM that rewrites the default OAuth2 format values:

authorization_url_format={authorization_url}?scope={scope}&client_id={client_id}&response_type=code&access_type=offline&redirect_uri={redirect_uri}
authorization_url=https://accounts.zoho.com/oauth/v2/auth

get_token_url_format={accounts-server}/oauth/v2/token
get_token_body_format=grant_type=authorization_code&client_id={client_id}&client_secret={client_secret}&redirect_uri={redirect_uri}&code={code}

refresh_token_url_format={accounts-server}/oauth/v2/token?refresh_token={refresh_token}&client_id={client_id}&client_secret={client_secret}&grant_type=refresh_token
refresh_token_body_format=

revoke_token_url_format={accounts-server}/oauth/v2/token/revoke?token={refresh_token}
revoke_token_body_format=

/tokenFields=<fields>

Use this option to explicitly define the field list saved in the OAuth1/OAuth2 token file.

For example:

/tokenFields=access_token,refresh_token,token_type,expires_in,valid_to

For Zoho CRM, which has additional fields, you might use:

/tokenFields=location,accounts-server,api_domain,access_token,refresh_token,token_type,expires_in,valid_to

In most cases, gsqlcmd detects such fields automatically and creates lists when loading an actual token file.

/tokenJson=<file>

Use this option to specify a file containing access and refresh tokens.

gsqlcmd updates these files automatically when acquiring or refreshing tokens, for example, in the get-token and refresh-token modes.

For example:

gsqlcmd refresh-token /clientJson=client_secret.json /tokenJson=access_token.json

Here’s an example of a token file acquired from the Google Search Console API:

{
  "access_token": "ya29.abcdefghijklmnopqrstuv-1234567890123456789-abcdefghijklmnopqrstu_123456789012345678-abc-abcdefghijklmnopqrstuvwx-1234567890123",
  "expires_in": 3600,
  "refresh_token": "1/ABCDEFGHIJKLMNOPQRST-abcdefghijklmnopqrstuv",
  "scope": "https://www.googleapis.com/auth/webmasters.readonly",
  "token_type": "Bearer"
}

/tokenType=<type>

Use this option to specify an OAuth2 token type.

For example:

/accessToken=12345 /tokenType=Bearer

"Bearer" is the default value.

This option also requires an access token specified with the /accessToken or /tokenJson option.

Alternatively, you can set the Authorization header directly using the /header option, like this:

"/header=Authorization: Bearer 12345"

/tokenUri=<URL>

Use this option to set the default URL for acquiring and refreshing an OAuth2 access token.

For example:

/token_uri=https://oauth2.googleapis.com/token

This option is useful for loading service URLs from exported client application files, such as those from Google.

If you configure the service manually, you can define the /getTokenUrl and /refreshTokenUrl options instead.

/urlParameters=<value>

Use this option to specify the URL parameters for a custom authentication method.

For example:

gsqlcmd download https://localhost/crm/contacts /urlParameters=api_key=key

The actual URL in this case would look like:

https://localhost/crm/contacts?api_key=key

/username=<username>

Use this option to set a username for web resources protected by Basic, Windows, or Forms authentication schemes.

For example:

gsqlcmd download https://localhost/crm/contacts /username=user /password=pass

If the tool cannot retrieve data using the provided credentials, try specifying the authentication method manually using the /auth option:

gsqlcmd download https://localhost/crm/contacts /auth=Forms /username=user /password=pass

/validTo=<datetime>

Use this option to set the expiration time for the OAuth1/OAuth2 token.

For example:

/validTo=2021-03-10T16:36:15.850Z

gsqlcmd uses this value to refresh tokens automatically.

Typically, you won't need to set this manually, as the exported token file contains this value.