Skip to content
Last updated: 2026-04-06
Guide

First Integration Guide

Connect to the Dxtra GraphQL API and make your first queries.

Prerequisites

Time: 45 minutes Required: Basic programming knowledge, Dxtra account with API key

Overview

Step Time Task
1 10 min Get API credentials
2 15 min Authenticate
3 15 min Make API calls
4 5 min Verify in dashboard

Step 1: Get API Credentials

  1. Log in to the Dxtra Dashboard
  2. Navigate to API Keys (in the sidebar)
  3. Click Create API Key
  4. Copy and securely store:
    • The Personal Access Token (shown only once)
    • Your Data Controller ID (visible in Settings > Organization)

Security

Store your API key securely. Never commit it to source control. Use environment variables.

Step 2: Authenticate

Exchange your Personal Access Token (PAT) for a JWT access token.

Endpoints:

Environment Auth URL GraphQL URL
Production https://auth.dxtra.ai https://api.dxtra.ai
Local Dev https://local.auth.local.dxtra.ai https://local.graphql.local.dxtra.ai
Bash
# Exchange PAT for JWT
curl -X POST "https://auth.dxtra.ai/v1/signin/pat" \
  -H "Content-Type: application/json" \
  -d '{"personalAccessToken": "YOUR_PAT"}'

Response:

JSON
{
  "session": {
    "accessToken": "eyJhbG...",
    "accessTokenExpiresIn": 3600,
    "refreshToken": "..."
  }
}

JavaScript
async function getAccessToken(pat) {
  const response = await fetch('https://auth.dxtra.ai/v1/signin/pat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ personalAccessToken: pat })
  });

  if (!response.ok) {
    throw new Error(`Authentication failed: ${response.status}`);
  }

  const data = await response.json();
  return data.session.accessToken;
}
Python
import requests

def get_access_token(pat: str) -> str:
    response = requests.post(
        'https://auth.dxtra.ai/v1/signin/pat',
        json={'personalAccessToken': pat}
    )
    response.raise_for_status()
    return response.json()['session']['accessToken']

The JWT token expires after 1 hour. Re-authenticate when you receive a 401 response.

See: Authentication Guide

Step 3: Make API Calls

Use the JWT token to query the GraphQL API.

Query Data Controllers

Bash
curl -X POST "https://api.dxtra.ai/v1/graphql" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "X-Hasura-Role: user" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { dataControllers { id title did createdAt } }"
  }'
JavaScript
async function queryGraphQL(jwt, query, variables = {}) {
  const response = await fetch('https://api.dxtra.ai/v1/graphql', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${jwt}`,
      'X-Hasura-Role': 'user',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query, variables })
  });

  const result = await response.json();
  if (result.errors) {
    throw new Error(result.errors[0].message);
  }
  return result.data;
}

// Query data controllers
const data = await queryGraphQL(jwt, `
  query {
    dataControllers {
      id
      title
      did
      createdAt
    }
  }
`);
console.log(data.dataControllers);
Python
import requests

def graphql_query(jwt: str, query: str, variables: dict = None):
    response = requests.post(
        'https://api.dxtra.ai/v1/graphql',
        headers={
            'Authorization': f'Bearer {jwt}',
            'X-Hasura-Role': 'user',
            'Content-Type': 'application/json'
        },
        json={'query': query, 'variables': variables or {}}
    )
    result = response.json()
    if 'errors' in result:
        raise Exception(result['errors'][0]['message'])
    return result['data']

# Query data controllers
data = graphql_query(jwt, '''
    query {
        dataControllers {
            id
            title
            did
            createdAt
        }
    }
''')
print(data['dataControllers'])

Create a Data Subject

Use the createDataSubject mutation to register a data subject:

Bash
curl -X POST "https://api.dxtra.ai/v1/graphql" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "X-Hasura-Role: user" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mutation CreateDataSubject($input: CreateDataSubjectInput!) { createDataSubject(input: $input) { dataSubjectId message } }",
    "variables": {
      "input": {
        "event": "signup",
        "dataControllerId": "YOUR_CONTROLLER_ID",
        "payload": {
          "displayName": "Test User",
          "email": "test@example.com",
          "country": "US"
        }
      }
    }
  }'
JavaScript
const result = await queryGraphQL(jwt, `
  mutation CreateDataSubject($input: CreateDataSubjectInput!) {
    createDataSubject(input: $input) {
      dataSubjectId
      message
    }
  }
`, {
  input: {
    event: 'signup',
    dataControllerId: 'YOUR_CONTROLLER_ID',
    payload: {
      displayName: 'Test User',
      email: 'test@example.com',
      country: 'US'
    }
  }
});
console.log('Created:', result.createDataSubject);
Python
result = graphql_query(jwt, '''
    mutation CreateDataSubject($input: CreateDataSubjectInput!) {
        createDataSubject(input: $input) {
            dataSubjectId
            message
        }
    }
''', {
    'input': {
        'event': 'signup',
        'dataControllerId': 'YOUR_CONTROLLER_ID',
        'payload': {
            'displayName': 'Test User',
            'email': 'test@example.com',
            'country': 'US'
        }
    }
})
print('Created:', result['createDataSubject'])

Step 4: Verify

Confirm your integration is working:

  1. Dashboard: Check that the data subject appears in Data Subject Support
  2. Activity Log: Verify the processing activity was recorded
  3. Compliance Score: Confirm the Assurance dashboard reflects the activity

Common Errors

Error Cause Solution
401 Unauthorized JWT expired or invalid Re-authenticate with PAT
403 Forbidden Missing or wrong role Add X-Hasura-Role: user header
Foreign key violation Invalid data controller ID Verify ID from dashboard

Next Steps