Skip to main content
Version: PromptQL

Authentication in APIs

Introduction​

PromptQL APIs use different authentication models depending on the operation type. Understanding these models is crucial for accessing the right endpoints with the appropriate credentials.

Authentication Models​

PromptQL APIs use two distinct authentication approaches:

User-Scoped Operations (JWT Bearer Token Required)​

These operations manage user-owned resources and require JWT authentication:

  • Threads API: Thread management, sharing, and pinned threads
  • Automations API: Automation management (create, list, get, delete)

Authentication Method: JWT Bearer token obtained through the PromptQL token refresh endpoint

Project-Scoped Operations (API Key Accepted)​

These operations access shared project resources and accept PromptQL API keys:

  • Natural Language API: Conversational queries
  • Execute Program API: Program execution
  • Threads API: Reading threads and feedback (when using API key)
  • Automations API: Running automations

Authentication Method: PromptQL API key as Bearer token

Getting JWT Tokens for User-Scoped Operations​

For user-scoped operations (like managing threads and automations), you need to obtain a JWT token using the PromptQL token refresh endpoint.

Prerequisites​

Before you can obtain a JWT token, ensure you have:

Token Acquisition Process​

The JWT token is obtained by making a POST request to the token refresh endpoint with your PAT and project ID.

Bash Example​

Get JWT token
JWT_TOKEN=$(curl -s -X POST "https://auth.pro.hasura.io/ddn/promptql/token" \
  -H "Authorization: pat <YOUR_PAT_OR_SERVICE_ACCOUNT_TOKEN>" \
  -H "x-hasura-project-id: <YOUR_PROJECT_ID>" \
  -H "Content-Type: application/json" \
  | jq -r '.token')
Use the token for user-scoped operations
curl -X GET "https://promptql.ddn.hasura.app/threads" \
  -H "Authorization: Bearer ${JWT_TOKEN}" \
  -H "Content-Type: application/json"
Token Expiration

JWT tokens have a limited lifespan. Implement token refresh logic in your applications to automatically obtain new tokens when needed.

DDN Data Source Authentication​

The examples below show how to authenticate with your DDN data sources when using PromptQL APIs. These are separate from the PromptQL API authentication described above.

Default​

By default, you can use the short-lived x-hasura-ddn-token to make requests against the Execute Program API:
{
  "code": "# Get Saving Private Ryan's details\nsql = \"\"\"\nSELECT series_title, overview, genre, director, imdb_rating, released_year\nFROM app.movies\nWHERE LOWER(series_title) = 'saving private ryan'\n\"\"\"\nmovie = executor.run_sql(sql)\n\nif len(movie) == 0:\n    executor.print(\"Movie not found\")\nelse:\n    movie = movie[0]\n    # Prepare text for classification\n    classification_text = f\"\"\"\nMovie: {movie['series_title']}\nOverview: {movie['overview']}\n\"\"\"",
  "promptql_api_key": "<YOUR_API_KEY>",
  "ai_primitives_llm": {
    "provider": "hasura"
  },
  "ddn": {
    "url": "https://<PROJECT_NAME>.ddn.hasura.app/v1/sql",
    "headers": {
      "x-hasura-ddn-token": "<YOUR_DDN_AUTH_TOKEN_FROM_THE_PLAYGROUND>"
    }
  },
  "artifacts": []
}

JWT & Webhook Mode​

If you're using JWT or Webhook Mode, you'll pass your authentication header:
{
  "code": "# Get Saving Private Ryan's details\nsql = \"\"\"\nSELECT series_title, overview, genre, director, imdb_rating, released_year\nFROM app.movies\nWHERE LOWER(series_title) = 'saving private ryan'\n\"\"\"\nmovie = executor.run_sql(sql)\n\nif len(movie) == 0:\n    executor.print(\"Movie not found\")\nelse:\n    movie = movie[0]\n    # Prepare text for classification\n    classification_text = f\"\"\"\nMovie: {movie['series_title']}\nOverview: {movie['overview']}\n\"\"\"",
  "promptql_api_key": "<YOUR_API_KEY>",
  "ai_primitives_llm": {
    "provider": "hasura"
  },
  "ddn": {
    "url": "https://<PROJECT_NAME>.ddn.hasura.app/v1/sql",
    "headers": {
      "authorization": "Bearer <YOUR_TOKEN>"
    }
  },
  "artifacts": []
}
Authorization Strategies

The example above uses the Bearer strategy for the tokenLocation. Your setup may be different; consult our auth docs for more information about setting up an authentication mode.