Authentication¶

Dxtra uses JWT-based authentication for secure API access. This guide covers personal access tokens and the JWT token exchange flow.

Personal Access Tokens¶

Personal Access Tokens (PATs) provide programmatic access to the GraphQL API. These are refresh tokens that can be exchanged for short-lived JWT access tokens.

Generating a Personal Access Token¶

Using Your Personal Access Token¶

Personal Access Tokens must be exchanged for JWT tokens before making API calls.

sequenceDiagram
    participant App as Your Application
    participant Auth as auth.dxtra.ai
    participant API as api.dxtra.ai

    App->>Auth: POST /v1/signin/pat
    Note over App,Auth: {"personalAccessToken": "PAT"}
    Auth-->>App: JWT + Refresh Token
    Note over Auth,App: {"session": {"accessToken": "JWT...", "refreshToken": "..."}}

    App->>API: GraphQL Query + JWT
    Note over App,API: Authorization: Bearer JWT<br/>X-Hasura-Role: user
    API-->>App: GraphQL Response

    alt Token Expired (401)
        API-->>App: 401 Unauthorized
        App->>Auth: POST /v1/signin/pat
        Auth-->>App: New JWT Token
        App->>API: Retry with New JWT
        API-->>App: Successful Response
    end

API Endpoints:

curl \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"personalAccessToken": "YOUR_PAT"}' \
  https://auth.dxtra.ai/v1/signin/pat

{
  "session": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "accessTokenExpiresIn": 3600,
    "refreshToken": "abc123...",
    "user": {
      "id": "user-uuid",
      "email": "user@example.com",
      "defaultRole": "dataSubject"
    }
  }
}

curl \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Hasura-Role: user" \
  --data '{"query": "query { dataControllers { id title } }"}' \
  https://api.dxtra.ai/v1/graphql

JWT Authentication (Client Applications)¶

For web applications and the Dxtra Dashboard, authentication uses JWT tokens.

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

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

  const data = await response.json();
  return {
    accessToken: data.session.accessToken,
    refreshToken: data.session.refreshToken
  };
};

import requests

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

const makeGraphQLCall = async (jwtToken, query, role = 'user') => {
  const response = await fetch('https://api.dxtra.ai/v1/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${jwtToken}`,
      'X-Hasura-Role': role
    },
    body: JSON.stringify({ query })
  });

  const result = await response.json();

  if (result.errors) {
    throw new Error(`GraphQL Error: ${result.errors[0].message}`);
  }

  return result.data;
};

import { NhostProvider, useAuthenticated } from '@nhost/react';
import { NhostClient } from '@nhost/nhost-js';

// Initialize Nhost client with custom domain
const nhost = new NhostClient({
  authUrl: 'https://auth.dxtra.ai',
  graphqlUrl: 'https://api.dxtra.ai/v1/graphql',
  storageUrl: 'https://storage.dxtra.ai',
});

function App() {
  return (
    <NhostProvider nhost={nhost}>
      <AuthenticatedApp />
    </NhostProvider>
  );
}

function AuthenticatedApp() {
  const isAuthenticated = useAuthenticated();

  if (!isAuthenticated) {
    return <LoginPage />;
  }

  return <Dashboard />;
}

Token Management¶

JWT Token Lifecycle¶

When a token expires, you receive a 401 Unauthorized response. Re-authenticate with your Personal Access Token to get a new JWT.

Token Refresh Example¶

const makeAuthenticatedRequest = async (personalAccessToken, query) => {
  let { accessToken } = await authenticateWithPAT(personalAccessToken);

  try {
    return await makeGraphQLCall(accessToken, query);
  } catch (error) {
    if (error.status === 401) {
      const { accessToken: newToken } = await authenticateWithPAT(personalAccessToken);
      return await makeGraphQLCall(newToken, query);
    }
    throw error;
  }
};

Proactive Token Refresh¶

For long-running applications, implement proactive token refresh:

class AuthManager {
  constructor(personalAccessToken) {
    this.pat = personalAccessToken;
    this.accessToken = null;
    this.refreshAt = null;
  }

  async getAccessToken() {
    const now = Date.now();
    if (!this.accessToken || now >= this.refreshAt) {
      const { accessToken, accessTokenExpiresIn } =
        await authenticateWithPAT(this.pat);

      this.accessToken = accessToken;
      // Refresh 2 minutes before expiration
      this.refreshAt = now + ((accessTokenExpiresIn - 120) * 1000);
    }

    return this.accessToken;
  }
}

Security Best Practices¶

Personal Access Token Management¶

• Keep tokens secret -- Never share or commit to version control
• Use environment variables -- Store in .env files (add to .gitignore)
• Rotate compromised tokens -- Delete and regenerate immediately if exposed
• Use separate tokens per environment -- Different tokens for dev/staging/production

Access Control¶

• Use appropriate roles -- Grant minimum necessary permissions
• Validate user roles -- Check X-Hasura-Role matches expected value
• Implement rate limiting -- Protect against abuse (see Rate Limits)

Token Handling¶

• Handle expiration gracefully -- Implement automatic refresh logic
• Store JWTs securely -- Memory only, never localStorage for sensitive apps
• Use HTTPS exclusively -- All API calls must use secure transport

DXTRA_PAT=your_personal_access_token_here
DXTRA_AUTH_URL=https://auth.dxtra.ai
DXTRA_API_URL=https://api.dxtra.ai

Technical Details¶

Security Features¶

Troubleshooting¶

Common Issues¶

curl -X POST https://auth.dxtra.ai/v1/signin/pat \
  -H "Content-Type: application/json" \
  -d '{"personalAccessToken": "YOUR_PAT"}'

Getting Help¶

If you encounter authentication issues:

1. Check token expiration -- JWTs expire after 1 hour
2. Verify endpoints -- Ensure using correct environment URLs
3. Review role permissions -- Confirm role has required access
4. Contact support -- Email privacy@dxtra.ai with error details

Next Steps¶

• GraphQL Reference -- Explore available queries and mutations
• Integrations -- Platform-specific implementation examples
• Error Handling -- Comprehensive error code reference