GraphQL API Reference¶

Dxtra's GraphQL API provides type-safe access to privacy compliance data.

API Information¶

Authentication Flow¶

Two-step authentication process for accessing the GraphQL API:

sequenceDiagram
    participant Client as Client Application
    participant Auth as auth.dxtra.ai
    participant API as api.dxtra.ai/v1/graphql

    Client->>Auth: 1. POST /v1/signin/pat
    Note over Client,Auth: {"personalAccessToken": "dxtra_pat_..."}

    Auth-->>Client: 2. Return JWT Session
    Note over Auth,Client: {"session": {"accessToken": "eyJ0..."}}

    Client->>API: 3. GraphQL Request
    Note over Client,API: Authorization: Bearer JWT<br/>X-Hasura-Role: user

    API-->>Client: 4. Data Response
    Note over API,Client: {"data": {...}}

Authentication Headers¶

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9... # (1)
X-Hasura-Role: user # (2)
Content-Type: application/json # (3)

Available Roles:

Core Data Types¶

Privacy data model for regulatory compliance operations:

• DataController -- Organizations managing personal data
• DataSubject -- Individuals whose data is processed
• ProcessingActivity -- Records of data processing operations
• RightsRequest -- Data subject privacy rights requests

Utility Types¶

• uuid -- Universally unique identifiers
• timestamptz -- Timezone-aware timestamps
• jsonb -- Structured JSON data

Query Examples¶

Data Subject Management¶

query FindDataSubject($dataSubjectId: uuid!, $dataControllerId: uuid!) {
  dataSubjects(
    where: {
      _and: [
        { id: { _eq: $dataSubjectId } },
        { dataControllerId: { _eq: $dataControllerId } }
      ]
    }
    limit: 1
  ) {
    id
    did
    dataControllerId
    createdAt
    updatedAt
    dataProcessingActivities(
      order_by: { triggeredAt: desc }
      limit: 10
    ) {
      id
      typeId
      triggeredAt
      type {
        label
        comment
      }
    }
  }
}

mutation CreateDataSubject($input: CreateDataSubjectInput!) {
  createDataSubject(input: $input) {
    dataSubjectId
    message
  }
}

{
  "input": {
    "event": "data_subject.create",
    "dataControllerId": "123e4567-e89b-12d3-a456-426614174000",
    "payload": {
      "displayName": "John Doe",
      "email": "john.doe@example.com",
      "country": "US"
    }
  }
}

Processing Activity Tracking¶

mutation LogProcessingActivity($activity: dataProcessingActivities_insert_input!) {
  insertDataProcessingActivity(object: $activity) {
    id
    dataSubjectId
    typeId
    sourceId
    triggeredAt
    fieldIds
    preferenceIds
    dataSubject {
      did
      dataController {
        title
      }
    }
    type {
      label
      comment
    }
    source {
      label
    }
  }
}

query GetProcessingActivities(
  $dataControllerId: uuid!,
  $startDate: timestamptz!,
  $endDate: timestamptz!,
  $limit: Int = 50
) {
  dataProcessingActivities(
    where: {
      dataSubject: { dataControllerId: { _eq: $dataControllerId } },
      triggeredAt: {
        _gte: $startDate,
        _lte: $endDate
      }
    }
    order_by: { triggeredAt: desc }
    limit: $limit
  ) {
    id
    typeId
    sourceId
    triggeredAt
    fieldIds
    preferenceIds
    dataSubject {
      id
      did
    }
    type {
      label
      comment
    }
    source {
      label
    }
  }
  processingActivityStats: dataProcessingActivitiesAggregate(
    where: {
      dataSubject: { dataControllerId: { _eq: $dataControllerId } },
      triggeredAt: { _gte: $startDate, _lte: $endDate }
    }
  ) {
    aggregate {
      count
    }
  }
}

Data Subject Rights¶

query GetRightsRequests($dataControllerId: uuid!) {
  dataSubjectsRightsRequests(
    where: {
      dataSubject: { dataControllerId: { _eq: $dataControllerId } }
    }
    order_by: { createdAt: desc }
  ) {
    id
    dataSubjectId
    requestType
    status
    description
    createdAt
    verified
    dataSubject {
      id
      did
      dataController {
        title
      }
    }
  }
}

mutation CreateRightsRequest($request: dataSubjectsRightsRequests_insert_input!) {
  insertDataSubjectsRightsRequest(object: $request) {
    id
    requestType
    status
    createdAt
    dataSubject {
      did
    }
  }
}

{
  "request": {
    "dataSubjectId": "456e7890-f12b-34c5-a678-900123456789",
    "requestType": "access",
    "description": "Request for all personal data",
    "verified": false,
    "status": "pending"
  }
}

Real-Time Subscriptions¶

WebSocket-based real-time updates for live privacy monitoring:

Live Activity Monitoring¶

subscription LiveProcessingActivities($dataControllerId: uuid!) {
  dataProcessingActivities(
    where: {
      dataSubject: { dataControllerId: { _eq: $dataControllerId } }
    }
    order_by: { triggeredAt: desc }
    limit: 50
  ) {
    id
    typeId
    sourceId
    triggeredAt
    dataSubject {
      id
      did
    }
    type {
      label
    }
    source {
      label
    }
  }
}

Rights Request Updates¶

subscription RightsRequestUpdates($dataControllerId: uuid!) {
  dataSubjectsRightsRequests(
    where: {
      dataSubject: { dataControllerId: { _eq: $dataControllerId } }
    }
    order_by: { createdAt: desc }
  ) {
    id
    requestType
    status
    createdAt
    verified
    dataSubject {
      id
      did
    }
  }
}

Query Patterns¶

Filtering¶

where: {
  status: { _eq: "active" },
  createdAt: { _gte: "2024-01-01" }
}

Sorting¶

order_by: { createdAt: desc }

Pagination¶

limit: 50
offset: 100

Error Handling¶

GraphQL error handling for robust integrations:

{
  "errors": [
    {
      "message": "Could not verify JWT: JWTExpired",
      "extensions": {
        "code": "access-denied",
        "path": "$"
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "field 'dataControllers' not found in type: 'query_root'",
      "locations": [{"line": 2, "column": 3}],
      "extensions": {
        "code": "validation-failed",
        "path": "$.selectionSet.dataControllers"
      }
    }
  ]
}

{
  "errors": [
    {
      "message": "invalid input syntax for type uuid: \"not-a-uuid\"",
      "locations": [{"line": 1, "column": 1}],
      "path": ["createDataSubject"],
      "extensions": {
        "code": "constraint-violation"
      }
    }
  ]
}

Schema Exploration¶

Schema Introspection¶

Explore the complete Dxtra privacy schema using GraphQL introspection:

query IntrospectionQuery {
  __schema {
    types {
      name
      description
      kind
      fields {
        name
        type {
          name
          kind
        }
      }
    }
    queryType {
      name
      fields {
        name
        description
      }
    }
    mutationType {
      name
      fields {
        name
        description
      }
    }
  }
}

Recommended GraphQL Clients¶

• GraphiQL -- Browser IDE with auto-completion and schema documentation
• Altair GraphQL -- Desktop application with multi-environment support
• Apollo Studio -- Enterprise GraphQL platform with schema registry

Best Practices¶

Performance¶

• Use specific field selection -- only request needed data
• Implement proper pagination for large datasets
• Cache frequently accessed data appropriately

Security¶

• Always include proper authentication headers
• Validate user permissions for data access
• Use parameterized queries to prevent injection

Error Handling¶

• GraphQL responses use standard format with data and errors fields
• Check for errors array in all responses
• Handle network timeouts with retry logic

Command Line Examples¶

# Configuration
API_KEY="your_dxtra_api_key_here"
AUTH_URL="https://auth.dxtra.ai/v1/signin/pat"
GRAPHQL_URL="https://api.dxtra.ai/v1/graphql"

# Get JWT token
JWT_TOKEN=$(curl -s -X POST "$AUTH_URL" \
  -H "Content-Type: application/json" \
  -d "{\"personalAccessToken\":\"$API_KEY\"}" \
  | jq -r '.session.accessToken')

# GraphQL query
curl -X POST "$GRAPHQL_URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "X-Hasura-Role: user" \
  -d '{"query": "query { dataControllers { id title did createdAt } }"}' \
  | jq '.'

# Authentication
JWT_RESPONSE=$(http POST https://auth.dxtra.ai/v1/signin/pat \
  personalAccessToken="$DXTRA_API_KEY")

JWT_TOKEN=$(echo "$JWT_RESPONSE" | jq -r '.session.accessToken')

# GraphQL Query
http POST https://api.dxtra.ai/v1/graphql \
  Authorization:"Bearer $JWT_TOKEN" \
  X-Hasura-Role:user \
  query='query { dataControllers { id title did createdAt } }'

Getting Started Checklist¶

• Active Dxtra account with API access
• API key generated via Developers page
• GraphQL client installed (GraphiQL, Altair, or preferred tool)
• Network access verified to api.dxtra.ai and auth.dxtra.ai

For the most up-to-date schema information, always use GraphQL introspection or refer to your GraphQL client's built-in documentation features.