Developers

Authentication

Complete guide to MindPeeker's authentication and authorization system

Authentication Overview

MindPeeker uses OAuth 2.0 for secure authentication and authorization. Our system supports multiple grant types, fine-grained permissions, and enterprise-grade security features to protect your applications and data.

Authentication Methods

<UAlert icon="i-heroicons-shield-check" title="Supported Authentication Flows" description="Choose the right authentication method for your use case" color="green"

Server-to-Server

Client Credentials Flow

API Key Authentication

Service Account Access

Background Processing

User-Based Applications

Authorization Code Flow

PKCE for Mobile Apps

Device Authorization Flow

Token Refresh and Renewal

Client Credentials Flow

Overview

The Client Credentials flow is ideal for server-to-server applications where your application needs to access MindPeeker APIs on its own behalf without user interaction.

Implementation

Step 1: Request Access Token:

curl -X POST "https://auth.mindpeeker.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&scope=remote-viewing:read remote-viewing:write"

Response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "remote-viewing:read remote-viewing:write",
  "issued_at": 1640995200
}

Step 2: Use Access Token:

curl -X GET "https://api.mindpeeker.com/v1/sessions" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

SDK Implementation

Node.js SDK:

const { MindPeekerClient } = require('@mindpeeker/sdk');

const client = new MindPeekerClient({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  grantType: 'client_credentials',
  scopes: ['remote-viewing:read', 'remote-viewing:write']
});

// Automatic token handling
const sessions = await client.sessions.list();

Python SDK:

from mindpeeker import MindPeekerClient

client = MindPeekerClient(
    client_id='your_client_id',
    client_secret='your_client_secret',
    grant_type='client_credentials',
    scopes=['remote-viewing:read', 'remote-viewing:write']
)

sessions = client.sessions.list()

Authorization Code Flow

Overview

The Authorization Code flow is recommended for web applications that need to access MindPeeker on behalf of users, with user consent and interactive authentication.

Implementation

Step 1: Redirect User for Authorization:

const authUrl = `https://auth.mindpeeker.com/oauth2/authorize?` +
  `response_type=code&` +
  `client_id=${encodeURIComponent(clientId)}&` +
  `redirect_uri=${encodeURIComponent(redirectUri)}&` +
  `scope=${encodeURIComponent('remote-viewing:read profile')}&` +
  `state=${encodeURIComponent(generatedState)}`;

// Redirect user to authUrl
window.location.href = authUrl;

Step 2: Handle Callback and Exchange Code:

// In your callback handler
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');
const state = urlParams.get('state');

// Verify state to prevent CSRF
if (state !== storedState) {
  throw new Error('Invalid state parameter');
}

// Exchange code for token
const tokenResponse = await fetch('https://auth.mindpeeker.com/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: clientId,
    client_secret: clientSecret,
    code: code,
    redirect_uri: redirectUri
  })
});

const tokens = await tokenResponse.json();

Step 3: Use Access Token:

// Store tokens securely
localStorage.setItem('access_token', tokens.access_token);
localStorage.setItem('refresh_token', tokens.refresh_token);

// Make authenticated requests
const response = await fetch('https://api.mindpeeker.com/v1/user/profile', {
  headers: {
    'Authorization': `Bearer ${tokens.access_token}`
  }
});

// Generate code verifier
const codeVerifier = crypto.getRandomValues(new Uint8Array(32))
  .reduce((str, byte) => str + byte.toString(16).padStart(2, '0'), '');

// Generate code challenge
const encoder = new TextEncoder();
const data = encoder.encode(codeVerifier);
const digest = await crypto.subtle.digest('SHA-256', data);
const codeChallenge = btoa(String.fromCharCode(...new Uint8Array(digest)))
  .replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');

Step 2: Authorization Request:

const authUrl = `https://auth.mindpeeker.com/oauth2/authorize?` +
  `response_type=code&` +
  `client_id=${clientId}&` +
  `redirect_uri=${redirectUri}&` +
  `code_challenge=${codeChallenge}&` +
  `code_challenge_method=S256&` +
  `scope=${encodeURIComponent('remote-viewing:read profile')}`;

// Open in browser or web view

Step 3: Token Exchange:

const tokenResponse = await fetch('https://auth.mindpeeker.com/oauth2/token', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  body: new URLSearchParams({
    grant_type: 'authorization_code',
    client_id: clientId,
    code: authorizationCode,
    redirect_uri: redirectUri,
    code_verifier: codeVerifier
  })
});

Token Management

Token Refresh

Automatic Refresh in SDKs:

const client = new MindPeekerClient({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  autoRefresh: true // Default: true
});

// SDK automatically handles token refresh

Manual Token Refresh:

curl -X POST "https://auth.mindpeeker.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=YOUR_REFRESH_TOKEN&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

Token Storage Best Practices

Server-Side Storage:

// Use secure, HTTP-only cookies
res.cookie('access_token', accessToken, {
  httpOnly: true,
  secure: true,
  sameSite: 'strict',
  maxAge: 3600000 // 1 hour
});

Client-Side Storage:

// Use secure storage mechanisms
const secureStorage = {
  set: (key, value) => {
    // Use secure storage API or encrypted storage
    sessionStorage.setItem(key, encrypt(value));
  },
  get: (key) => {
    const encrypted = sessionStorage.getItem(key);
    return encrypted ? decrypt(encrypted) : null;
  }
};

Scopes and Permissions

Available Scopes

Remote Viewing Scopes:

remote-viewing:read - Read session data and results
remote-viewing:write - Create and manage sessions
remote-viewing:delete - Delete sessions and data
remote-viewing:admin - Administrative access

Dowsing Scopes:

dowsing:read - Read dowsing results and data
dowsing:write - Create dowsing requests
dowsing:delete - Delete dowsing data
dowsing:admin - Administrative access

Analytics Scopes:

analytics:read - Read analytics and reports
analytics:export - Export analytics data
analytics:admin - Administrative access

User Scopes:

profile - Read user profile information
email - Read user email address
organizations:read - Read organization data
organizations:write - Manage organization settings

Scope Combinations

Common Combinations:

// Basic application access
const basicScopes = ['remote-viewing:read', 'profile'];

// Full application access
const fullScopes = [
  'remote-viewing:read',
  'remote-viewing:write',
  'dowsing:read',
  'dowsing:write',
  'analytics:read',
  'profile'
];

// Administrative access
const adminScopes = [
  'remote-viewing:admin',
  'dowsing:admin',
  'analytics:admin',
  'organizations:write'
];

curl -X POST "https://api.mindpeeker.com/v1/api-keys" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production API Key",
    "scopes": ["remote-viewing:read", "remote-viewing:write"],
    "expires_at": "2024-12-31T23:59:59Z"
  }'

Use API Key:

curl -X GET "https://api.mindpeeker.com/v1/sessions" \
  -H "X-API-Key: your_api_key_here"

API Key Management

List API Keys:

const apiKeys = await client.apiKeys.list();

Revoke API Key:

await client.apiKeys.revoke('key_id_here');

Rotate API Key:

const newKey = await client.apiKeys.rotate('key_id_here');

Security Best Practices

Credential Management

Environment Variables:

MINDPEEKER_CLIENT_ID=your_client_id
MINDPEEKER_CLIENT_SECRET=your_client_secret
MINDPEEKER_API_KEY=your_api_key

Secure Configuration:

const config = {
  clientId: process.env.MINDPEEKER_CLIENT_ID,
  clientSecret: process.env.MINDPEEKER_CLIENT_SECRET,
  environment: process.env.NODE_ENV || 'development'
};

Token Security

Token Validation:

function validateToken(token) {
  try {
    // Decode JWT payload (without verification for demo)
    const payload = JSON.parse(atob(token.split('.')[1]));
    
    // Check expiration
    if (payload.exp < Date.now() / 1000) {
      throw new Error('Token expired');
    }
    
    // Check issuer
    if (payload.iss !== 'https://auth.mindpeeker.com') {
      throw new Error('Invalid issuer');
    }
    
    return true;
  } catch (error) {
    console.error('Token validation failed:', error);
    return false;
  }
}

Secure Token Storage:

// Use secure storage for tokens
const tokenStorage = {
  setToken: (token) => {
    // Store in secure HTTP-only cookie or secure storage
    document.cookie = `token=${token}; HttpOnly; Secure; SameSite=Strict`;
  },
  
  getToken: () => {
    // Retrieve from secure storage
    return document.cookie.replace(/(?:(?:^|.*;\s*)token\s*\=\s*([^;]*).*$)|^.*$/, '$1');
  },
  
  clearToken: () => {
    // Clear token from storage
    document.cookie = 'token=; HttpOnly; Secure; SameSite=Strict; expires=Thu, 01 Jan 1970 00:00:00 GMT';
  }
};

Error Handling

Authentication Errors:

try {
  const response = await client.sessions.create(sessionData);
} catch (error) {
  if (error.status === 401) {
    // Token expired or invalid
    await refreshToken();
    // Retry request
    const response = await client.sessions.create(sessionData);
  } else if (error.status === 403) {
    // Insufficient permissions
    console.error('Insufficient permissions for this operation');
  } else {
    // Other error
    console.error('Request failed:', error);
  }
}

Rate Limiting:

const handleRateLimit = async (error) => {
  if (error.status === 429) {
    const retryAfter = error.headers['retry-after'] || 60;
    console.log(`Rate limited. Retrying after ${retryAfter} seconds`);
    
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    // Retry request
    return true;
  }
  return false;
};

Enterprise Authentication

SAML Integration

SAML Configuration:

const samlConfig = {
  entryPoint: 'https://auth.mindpeeker.com/saml/login',
  issuer: 'your-entity-id',
  cert: 'mindpeeker-certificate.pem',
  privateKey: 'your-private-key.pem',
  callbackUrl: 'https://your-app.com/auth/saml/callback'
};

LDAP Integration

LDAP Authentication:

const ldapConfig = {
  url: 'ldap://your-ldap-server.com',
  bindDN: 'cn=admin,dc=company,dc=com',
  bindCredentials: 'admin-password',
  searchBase: 'ou=users,dc=company,dc=com',
  searchFilter: '(uid={{username}})'
};

Need help with authentication? Check out our API Reference for detailed endpoint documentation, or contact our developer support at developers@mindpeeker.com.

Platform Overview

Comprehensive overview of MindPeeker's psychic intelligence platform architecture and capabilities

API Reference

Complete API reference documentation for MindPeeker platform