Skillprint API Authentication Guide

This guide covers the authentication methods available for integrating with the Skillprint API, including code examples for different use cases. All endpoints are accessible via https://qa-marketplace.skillprint.co/.

Authentication Methods

Before using these endpoints, make sure you have:

1. A Partner API key (format: Api-Key <your_partner_key>)
2. Configured your allowed CORS origins

1. User Token Authentication

The Knox token-based system requires including the token in the X-Auth-Token header. You can provide the token in two formats:

• Prefixed format: Token <your_token>
• Raw format: <your_token>

Example using Python:

import requests

def make_authenticated_request(token):
    headers = {
        'X-Auth-Token': f'Token {token}',
        'Content-Type': 'application/json'
    }
    
    # Get user recommendations
    response = requests.get(
        'users/api/recommendations/',
        headers=headers
    )
    return response.json()

Example using JavaScript:

async function makeAuthenticatedRequest(token) {
    const headers = {
        'X-Auth-Token': `Token ${token}`,
        'Content-Type': 'application/json'
    };
    
    // Get user favorites
    const response = await fetch('users/api/favorites/', {
        method: 'GET',
        headers: headers
    });
    return await response.json();
}

2. Partner API Key Authentication

Partner authentication requires an API key in the Authorization header using the format: Api-Key <your_key>. The key must correspond to a valid partner record and will be provided by the Skillprint team.

Example using Python:

import requests

def make_partner_request(api_key):
    headers = {
        'Authorization': f'Api-Key {api_key}',
        'Content-Type': 'application/json'
    }
    
    # Get organization sessions
    response = requests.get(
        'games/api/sessions/',
        headers=headers
    )
    return response.json()

Example using Java:

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class SkillprintClient {
    private final HttpClient client = HttpClient.newHttpClient();
    private final String apiKey;

    public SkillprintClient(String apiKey) {
        this.apiKey = apiKey;
    }

    public String getPartnerSessions() throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("games/api/sessions/"))
            .header("Authorization", "Api-Key " + apiKey)
            .header("Content-Type", "application/json")
            .GET()
            .build();

        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
        return response.body();
    }
}

Returns sessions with:

• Session identifiers
• Game details
• Duration
• Skill and mood scores
• Generated content and tips

3. SPA Origin Validation

Requests from approved CORS origins are automatically allowed. The following origins are configured:

• https://marketplace.staging.skillprint.co
• https://app.staging.skillprint.co
• https://app.skillprint.co
• https://qa-marketplace.skillprint.co

API Access Levels

Public Endpoints (No Authentication Required)

SPA/API Key Required Endpoints

• games/api/skills/ - List available skills
• games/api/moods/ - List available moods
• games/api/search/ - Game search
• games/api/catalog/ - Game catalog
• games/api/surveys/* - Skill/mood surveys
• games/api/telemetry - Session telemetry

Example using JavaScript for public endpoints:

async function getGameMap() {
    const response = await fetch('games/api/moods/', {
        method: 'GET',
        headers: {
            'Content-Type': 'application/json'
        }
    });
    return await response.json();
}

User Authentication Required Endpoints

• games/api/favorites/* - Manage favorite games
• games/api/sessions/claim - Claim sessions
• games/api/recommendations/ - Get personalized recommendations
• games/api/surveys/mood/ - Submit a new post-game mood survey
• games/api/surveys/skill/ - Submit a new post-game skill survey
• scoring/api/profiles/ - Retrieve the Skillprint profile for the user
• scoring/api/mood-visualization/ - Retrieve mood analytics for the user
• scoring/api/skill-progression/ - Retrieve skill analytics progression for the user

Partner Access Endpoints

• partners/api/partner-sessions/* - View organization's sessions
  • Requires valid partner API key
  • Scoped to organization's data only
• games/api/record-session/{{session_id}}/ - Upload media to session

Mixed Access Endpoints

• games/api/sessions/ - Session management
  • Partners can see organization's sessions
  • Users can see their own sessions
  • Both can see user's sessions within organization
  • Partners can create a new session

Error Handling

The API returns standard HTTP status codes:

• 401 - Invalid or missing authentication
• 403 - Valid authentication but insufficient permissions
• 404 - Resource not found
• 500 - Server error

Example error handling in Python:

def handle_api_request(token, endpoint):
    try:
        response = requests.get(
            f'games/api/{endpoint}',
            headers={'X-Auth-Token': f'Token {token}'}
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            return "Authentication failed"
        elif e.response.status_code == 403:
            return "Insufficient permissions"
        else:
            return f"API error: {e.response.status_code}"

Best Practices

1. Store API keys and tokens securely
2. Implement proper error handling
3. Use appropriate authentication method based on access needs
4. Include proper Content-Type headers
5. Validate responses before processing
6. Implement retry logic for failed requests
7. Log authentication failures for monitoring

Remember to replace the base URL ([api.staging.skillprint.co](https://qa-marketplace.skillprint.co/)) with your appropriate environment endpoint in production.

iFrame Implementation

Basic iFrame Setup

The Skillprint application can be embedded in your web application using an iFrame. Here's how to implement it with different authentication methods:

<style>
    .skillprint-frame {
        position: absolute;
        left: 0px;
        top: 0px;
        width: 100vw;
        height: 100vh;
        border: none;
    }
</style>

<iframe 
    class="skillprint-frame"
    allow="display-capture;microphone;camera"
    id="skillprintFrame"
></iframe>

Implementation with User Token

// Implementation using User Token Authentication
async function loadSkillprintWithUserToken(userToken) {
    const iframe = document.getElementById('skillprintFrame');
    
    // Add token to URL as a query parameter
    const baseUrl = 'https://marketplace.staging.skillprint.co/discover';
    const url = new URL(baseUrl);
    url.searchParams.append('auth_token', userToken);
    
    iframe.src = url.toString();
}

// Usage
loadSkillprintWithUserToken('your-user-token');

Implementation with Partner API Key

// Implementation using Partner API Key
async function loadSkillprintWithApiKey(apiKey) {
    const iframe = document.getElementById('skillprintFrame');
    
    // Add API key to URL as a query parameter
    const baseUrl = 'https://marketplace.staging.skillprint.co/discover';
    const url = new URL(baseUrl);
    url.searchParams.append('api_key', apiKey);
    
    iframe.src = url.toString();
}

// Usage
loadSkillprintWithApiKey('your-partner-api-key');

Full Implementation Example

<!DOCTYPE html>
<html>
<head>
    <title>Skillprint Integration</title>
    <style>
        .skillprint-frame {
            position: absolute;
            left: 0px;
            top: 0px;
            width: 100vw;
            height: 100vh;
            border: none;
        }
    </style>
</head>
<body>
    <iframe 
        class="skillprint-frame"
        allow="display-capture;microphone;camera"
        id="skillprintFrame"
    ></iframe>

    <script>
        // Function to handle authentication errors
        function handleAuthError(error) {
            console.error('Authentication error:', error);
            // Implement your error handling here
        }

        // Function to initialize Skillprint with either token type
        async function initializeSkillprint(authType, token) {
            try {
                const iframe = document.getElementById('skillprintFrame');
                const baseUrl = 'https://marketplace.staging.skillprint.co/discover';
                const url = new URL(baseUrl);

                // Add appropriate authentication parameter based on type
                if (authType === 'user') {
                    url.searchParams.append('auth_token', token);
                } else if (authType === 'partner') {
                    url.searchParams.append('api_key', token);
                } else {
                    throw new Error('Invalid authentication type');
                }

                // Load the iframe with the authenticated URL
                iframe.src = url.toString();

                // Optional: Add event listener for iframe load completion
                iframe.onload = () => {
                    console.log('Skillprint interface loaded successfully');
                };

                // Optional: Add event listener for iframe communication
                window.addEventListener('message', (event) => {
                    // Verify origin for security
                    if (event.origin === 'https://marketplace.staging.skillprint.co') {
                        console.log('Message from Skillprint:', event.data);
                    }
                });

            } catch (error) {
                handleAuthError(error);
            }
        }

        // Example usage with user token
        // initializeSkillprint('user', 'your-user-token');

        // Example usage with partner API key
        // initializeSkillprint('partner', 'your-partner-api-key');
    </script>
</body>
</html>

Security Considerations

1. Always validate the authentication token/API key before initializing the iframe
2. Use HTTPS for all communications
3. Implement proper origin validation for postMessage communications
4. Store authentication credentials securely
5. Implement proper error handling and user feedback
6. Consider implementing a session timeout mechanism

Usage guide

See the Usage page for detailed analytics instructions.