Users & Authentication

TypeDB requires authentication for all client connections. Understanding how authentication works across different deployments and how to manage users programmatically is essential for building secure applications.

Authentication fundamentals

Required credentials

Every TypeDB driver connection requires valid user credentials:

  • Username: The name of a TypeDB user

  • Password: The corresponding password for that user

#!test
#{{
from typedb.driver import *
#}}
from typedb.driver import Credentials

# All connections require valid credentials
credentials = Credentials("admin", "password")

#{{
address = "localhost:1729"
options = DriverOptions(is_tls_enabled=True, tls_root_ca_path=None)
#}}

driver = TypeDB.driver(address, credentials, options)

Default users

TypeDB installations come with a default administrative user:

  • Username: admin

  • Cloud password: Set during cluster creation

  • Community Edition / Enterprise default password: password

Always change default passwords before deploying to production environments.

HTTP endpoint authentication

The HTTP endpoint uses token-based authentication instead of direct credentials.

Note that if you are using an official TypeDB HTTP Driver, this process is handled by the library.

For the full reference, see the TypeDB HTTP API documentation.

Token acquisition

First, exchange your credentials for a temporary token:

curl --request POST \
  --url http://localhost:8000/v1/signin \
  --json '{"username": "admin", "password": "password"}'

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Using tokens

Include the token in the Authorization header for subsequent requests:

curl --request GET \
  --url http://localhost:8000/v1/databases \
  --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'

Token lifecycle

  • Expiration: Tokens expire after a configurable period (default: 30 minutes)

  • Renewal: Obtain new tokens by re-authenticating

  • Revocation: Tokens are invalidated when servers restart

Updating passwords

It’s possible to change user passwords programmatically. The admin user can also be used to update any user’s password, all other users can only update their own password.

Python
#!test[reset-after]
from typedb.driver import *

DB_NAME = "my_database"
address = "localhost:1729"
credentials = Credentials("admin", "password")
options = DriverOptions(is_tls_enabled=True, tls_root_ca_path=None)

with TypeDB.driver(address, credentials, options) as driver:
    driver.users.create("demo_user", "test_password")

user_credentials = Credentials("demo_user", "test_password")
with TypeDB.driver(address, user_credentials, options) as driver:
    driver.users.get_current_user().update_password("password")
    print("Demo user updated password successfully")

with TypeDB.driver(address, credentials, options) as driver:
    driver.users.get("demo_user").update_password("externally_set_password")
    print("Admin updated demo user's password successfully")

Security considerations

  • Enable encryption for all production deployments

  • Use TLS certificates from trusted Certificate Authorities

  • Avoid plain-text connections over untrusted networks

  • Configure firewalls to restrict database access

Authentication errors

Common authentication errors and solutions:

Invalid credentials

Error: "Authentication failed" or "Invalid username/password"

Solutions:

  • Verify username and password are correct

  • Check if user exists

  • Ensure user hasn’t been deleted

Connection refused

Error: "Connection refused" or "Unable to connect"

Solutions:

  • Verify server address and port

  • Check if TypeDB server is running

  • Check that TLS is either enabled on both driver and server, or disabled on both driver and server

  • Ensure network connectivity

TLS/encryption errors

Error: "TLS handshake failed" or "Certificate validation failed"

Solutions:

  • Check that TLS is either enabled on both driver and server, or disabled on both driver and server

  • Check certificate paths and validity