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.

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.