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.
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 withAUTO_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 usingCREATE 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.5 or before, 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 3.6 or later, the return value is just the token.
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
See this for more details.
refreshToken()
refreshToken(secret: str, token: str = "", 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 usingCREATE 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 or if an authentication error
occurs.
Note:
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 usingCREATE 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
See this for more details.