Authentication Methods

In the Graphistry 2.0 REST API, authentication is crucial for security and access control. Currently, there are three methods to obtain JWT tokens:

1. Username and Password
2. Personal API Key
3. Single Sign-On (SSO)

1. Password Authentication

Use your account credentials to get a short-lived token (~1 hour). This token is required for performing REST API actions. Tokens are valid for up to 24 hours, requiring daily re-login with full credentials. For more information, see Personal API Key Authentication and Single Sign-On (SSO) Authentication.

2. Personal API Key Authentication

To authenticate using a personal API key:

1. Navigate to your profile menu and select "Manage API Keys".
2. Generate a Personal Key ID and Secret Key. Note: The Personal Secret Key will not be visible again after leaving this screen.
3. Use the Personal Key ID and Secret Key to authenticate by making a POST request with the following format:

  curl -X POST -H "Authorization: PersonalKey ${PERSONAL_KEY_ID}:${PERSONAL_KEY_SECRET}" https://${GRAPHISTRY_HOST}/api/v2/auth/pkey/jwt/
  

This request will return a JWT token that can be used for subsequent API requests.

3. Global Single Sign-On (SSO)

SSO authentication redirects you to the site-wide SSO system for login.

4. Single Sign-On (SSO) with Organization (IDP)

For organizations using IDP (Identity Provider) with SSO, the authentication process involves two steps and two API calls:

1. Initiate SSO Authentication: The first step is to initiate the SSO authentication process for your organization. This is done by making a GET request to the SSO login API endpoint. This request will redirect you to the organization's SSO login page.
2. Retrieve the JWT Token: After successfully logging in through the SSO system, you will receive a response that includes a 'state' parameter. This 'state' is a unique identifier for your session. You then use this 'state' to make a second API call to retrieve your JWT token.

5. Single-Use Token Gateway (Admin Only)

The Single-Use Token Gateway enables one-time token-based access to Graphistry datasets for external, unauthenticated users. This authentication method is restricted to administrators (staff OR superuser) and provides temporary access without requiring full account creation.

Use Case: Admins can generate secure, single-use URLs for external users to access specific datasets without creating permanent accounts or sharing credentials.

Flow:

1. Admin calls GET /api/v2/generate/single-use-url/?username=any_username&dataset_id=DATASET_ID with Bearer token
2. System returns magic login URL: {"single_use_url": "https://domain/magic-login/?sst=TOKEN"}
3. Admin sends magic login URL to external user
4. External user clicks the magic login link
5. User gains temporary access to the specified dataset only
6. Admin can immediately revoke access using GET /api/v2/logout-user/username/ to force logout and remove all permissions

Security Features:

• One-time use tokens (expire after first use)
• Limited access scope (only target dataset)
• Dual-layer time expiration (see Configuration below)
• Admin-controlled revocation (force logout active users)

Access Control:

Once external users click the magic login link, they gain active sessions until natural expiry. Admins can use the logout endpoint to immediately revoke access for security purposes - useful for ending demos, responding to security concerns, or removing access when collaboration ends.

Configuration

The following settings control the behavior of the Single-Use Token Gateway:

Note: In addition to the configurable sesame token settings above, magic links have a hardcoded 7-day database record expiration. ShareLinkUser records are automatically cleaned up after 7 days from generation, making magic links completely invalid regardless of usage.

Cross-Origin Iframe Embedding

To embed Graphistry visualizations in an <iframe> on a different origin (for example, embedding into Louie or another web app), the Graphistry server must issue session cookies with SameSite=None; Secure. Otherwise the browser will drop the auth cookies inside the embedded iframe and the user will see an auth loop or a "This content is blocked" message.

Set both flags in the Graphistry server's environment configuration:

COOKIE_SECURE=true
COOKIE_SAMESITE=None

Notes:

• COOKIE_SECURE=true requires Graphistry to be served over HTTPS. TLS termination at the reverse proxy or ingress (e.g. Caddy, nginx-ingress, k8s ingress controller) is sufficient.
• If DJANGO_SECURE_SSL_REDIRECT=true is already set (the operator has opted into HTTPS-only mode), COOKIE_SECURE auto-derives to true; no need to set it twice.
• When TLS terminates at an upstream load balancer or ingress controller (common in Kubernetes), set COOKIE_SECURE=true explicitly and leave DJANGO_SECURE_SSL_REDIRECT unset. This stamps cookies as Secure without making Django itself issue HTTP-to-HTTPS redirects, which can interfere with LB health checks.
• If COOKIE_SECURE=true and COOKIE_SAMESITE is unset, it auto-derives to None; setting it explicitly is recommended for clarity.
• Misconfiguration guard: setting COOKIE_SAMESITE=None (case-insensitive) without COOKIE_SECURE=True raises ImproperlyConfigured at startup, because browsers reject SameSite=None cookies that are not Secure.
• These flags apply to all three auth cookies: sessionid, csrftoken, and graphistry_jwt.
• The embedding host must also allow the Graphistry origin in its CSP frame-src and child-src. For Louie embedding, see the Graphistry Iframe Blocked in Louie runbook.

HSTS note when re-testing on plain HTTP: if a previous HTTPS visit set HSTS (Graphistry production defaults SECURE_HSTS_SECONDS), the browser will auto-upgrade http:// URLs for that hostname for the cache TTL. If a plain-HTTP regression test silently redirects to HTTPS, clear HSTS for the host via chrome://net-internals/#hsts (or the Firefox equivalent).

Verify in the browser DevTools, under Application > Cookies on the Graphistry host. Check all three cookies individually. They are written by different code paths and can disagree if misconfigured:

All three must match. If graphistry_jwt disagrees with the other two, the JWT cookie's SameSite wiring may be missing; see JWT_AUTH in config/settings/base.py.

Flow Diagram

Admin  → Generate URL
       → Send the URL to User
User   → /magic-login?sesame=... → Logs in
       → /graph/graph.html?dataset=... (auto)
Admin  → /logout-user/<username>/ → revokes session
User   → Logout

Using REST API for Authentication

Below are examples of REST API calls for each authentication method:

{"token": str}

          curl -X POST -H "Authorization: PersonalKey ${PERSONAL_KEY_ID}:${PERSONAL_KEY_SECRET}" https://${GRAPHISTRY_HOST}/api/v2/auth/pkey/jwt/

curl -X GET http://localhost/api/v2/g/sso/oidc/login/

curl -X GET http://localhost/api/v2/o/str:slug/sso/oidc/login/str:idp_name/

curl -X GET http://localhost/api/v2/o/sso/oidc/jwt/{state}/

For further details and language-specific implementations, please refer to our Python client library documentation.