Authentication Functions

The functions on this page authenticate connections and manage TigerGraph credentials. All functions in this module are called as methods on a TigerGraphConnection object.

getSecrets()

getSecrets() → dict

Issues a SHOW SECRET GSQL statement and returns the secret generated by that statement. Secrets are unique strings that serve as credentials when generating authentication tokens.

Returns:

A dictionary of alias: secret_string pairs.

Notes:

This function returns the masked version of the secret. The original value of the secret cannot be retrieved after creation.

showSecrets()

showSecrets() → dict

DEPRECATED

Use getSecrets() instead.

createSecret()

createSecret(alias: str = "", withAlias: bool = False) → Union[str, dict]

Issues a CREATE SECRET GSQL statement and returns the secret generated by that statement. Secrets are unique strings that serve as credentials when generating authentication tokens.

Parameters:

  • alias: The alias of the secret.
    The system will generate a random alias for the secret if the user does not provide an alias for that secret. Randomly generated aliases begin with AUTO_GENERATED_ALIAS_ and include a random 7-character string.

  • withAlias: Return the new secret as an {"alias": "secret"} dictionary. This can be useful if an alias was not provided, for example if it is auto-generated).

Returns:

The secret string.

Notes:

Generally, secrets are generated by the database administrator and used to generate a token. If you use this function, please consider reviewing your internal processes of granting access to TigerGraph instances. Normally, this function should not be necessary and should not be executable by generic users.

dropSecret()

dropSecret(alias: Union[str, list], ignoreErrors: bool = True) → str

Drops a secret.
See this for more details.

Parameters:

  • alias: One or more alias(es) of secret(s).

  • ignoreErrors: Ignore errors arising from trying to drop non-existent secrets.

Raises:

TigerGraphException if a non-existent secret is attempted to be dropped (unless ignoreErrors is True). Re-raises other exceptions.

getToken()

getToken(secret: str = None, setToken: bool = True, lifetime: int = None) → Union[tuple, str]

Requests an authorization token.

This function returns a token only if REST++ authentication is enabled. If not, an exception will be raised.
See this for more details.

Parameters:

  • secret (str, Optional): The secret (string) generated in GSQL using CREATE SECRET.
    See this for more details.

  • setToken (bool, Optional): Set the connection’s API token to the new value (default: True).

  • lifetime (int, Optional): Duration of token validity (in seconds, default 30 days = 2,592,000 seconds).

Returns:

If your TigerGraph instance is running version ⇐3.10, the return value is a tuple of (<token>, <expiration_timestamp_unixtime>, <expiration_timestamp_ISO8601>). The return value can be ignored, as the token is automatically set for the connection after this call.

If your TigerGraph instance is running version 4.0, the return value is a tuple of `(<token>, <expiration_timestamp_with_local_time>).

The expiration timestamp’s time zone might be different from your computer’s local time zone.

Raises:

TigerGraphException if REST++ authentication is not enabled or if an authentication error occurred.

Endpoint:

  • POST /requesttoken (In TigerGraph versions 3.x)
    See this for more details.

  • POST /gsql/v1/tokens (In TigerGraph versions 4.x)

refreshToken()

refreshToken(secret: str, token: str = "", setToken: bool = True, lifetime: int = None) → tuple

Extends a token’s lifetime.

This function works only if REST++ authentication is enabled. If not, an exception will be raised.
See this for more details.

Parameters:

  • secret: The secret (string) generated in GSQL using CREATE SECRET.
    See this for more details.

  • token: The token requested earlier. If not specified, refreshes current connection’s token.

  • lifetime: Duration of token validity (in seconds, default 30 days = 2,592,000 seconds) from current system timestamp.

Returns:

A tuple of (<token>, <expiration_timestamp_unixtime>, <expiration_timestamp_ISO8601>). The return value can be ignored.
New expiration timestamp will be now + lifetime seconds, not current expiration timestamp + lifetime seconds.

The expiration timestamp’s time zone might be different from your computer’s local time zone.

Raises:

TigerGraphException if REST++ authentication is not enabled, if an authentication error occurs, or if calling while using TigerGraph 4.x.

Note: Not avaliable on TigerGraph version 4.x

Endpoint:

  • PUT /requesttoken
    See this for more details.

deleteToken()

deleteToken(secret, token = None, skipNA = True) → bool

Deletes a token.

This function works only if REST++ authentication is enabled. If not, an exception will be raised.
See this for more details.

Parameters:

  • secret: The secret (string) generated in GSQL using CREATE SECRET.
    See this for more details.

  • token: The token requested earlier. If not specified, deletes current connection’s token, so be careful.

  • skipNA: Don’t raise an exception if the specified token does not exist.

Returns:

True, if deletion was successful, or if the token did not exist but skipNA was True.

Raises:

TigerGraphException if REST++ authentication is not enabled or an authentication error occurred, for example if the specified token does not exist.

Endpoint:

  • DELETE /requesttoken (In TigerGraph version 3.x)
    See this for more details.

  • DELETE /gsql/v1/tokens (In TigerGraph version 4.x)