Matik API Guides | Matik API Documentation

Quick Start Guide

March 30, 2025 · 4 min read

Matik API Team

This guide will help you get started with the Matik API quickly. We'll cover the basics of setting up your client, authenticating, and making your first API call to generate a presentation.

Prerequisites

Before you begin, make sure you have:

A Matik account with API access
Basic understanding of RESTful APIs and OAuth 2.0

Getting Started

Create a Client

To get started with the API, follow these steps:

Reach out to your account manager to enable the Matik REST API in your account.
Navigate to the enterprise settings page by clicking on your avatar in the upper right and selecting "Enterprise Settings".
Click on the "Clients" tab on the enterprise settings page.
Create a new client, copying the client secret to somewhere secure when you see it.
Set the redirect URI to the location in your domain to complete the authorization.

Implement OAuth 2.0

Once you've set up the client in Matik, you can implement the OAuth 2.0 authorization flow:

Redirect the user to the authorization URL:

const authUrl = 'https://app.matik.io/oauth/authorize' + 
  '?response_type=code' +
  '&client_id=YOUR_CLIENT_ID' +
  '&redirect_uri=YOUR_REDIRECT_URI' +
  '&scope=producer+consumer' +
  '&state=OPTIONAL_STATE_VALUE';

// Redirect user to authUrl

After the user authorizes your application, they will be redirected to your redirect URI with an authorization code. Exchange this code for access and refresh tokens:

async function getTokens(code, clientId, clientSecret, redirectUri) {
  try {
    const response = await fetch('https://app.matik.io/api/v1/oauth/token/', {
      method: 'POST',
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: new URLSearchParams({
        grant_type: 'authorization_code',
        client_id: clientId,
        client_secret: clientSecret,
        redirect_uri: redirectUri,
        code: code,
        scope: 'producer consumer'
      })
    });

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

    const data = await response.json();

    // Store these tokens securely
    const accessToken = data.access_token;
    const refreshToken = data.refresh_token;

    return { accessToken, refreshToken };
  } catch (error) {
    console.error('Error obtaining tokens:', error);
    throw error;
  }
}

Once the access token expires, you can refresh it using the refresh token.

Generate a Presentation

With your access token, you can now generate a presentation:

async function generatePresentation(accessToken, templateId, inputs) {
  try {
    const response = await fetch('https://app.matik.io/api/1.0/presentations', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        name: "My Generated Presentation",
        template_id: templateId,
        inputs: inputs  // Object containing input name/value pairs
      })
    });

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

    const data = await response.json();

    // The API returns the presentation ID and sets the Location header
    const presentationId = data.id;
    const statusUrl = response.headers.get('location');

    return { presentationId, statusUrl };
  } catch (error) {
    console.error('Error generating presentation:', error);
    throw error;
  }
}

Check Presentation Status

Presentations are generated asynchronously. You need to poll the status endpoint:

async function checkPresentationStatus(accessToken, statusUrl) {
  try {
    const response = await fetch(statusUrl, {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    });

    // Accept 200 (in progress) and 303 (completed)
    if (response.status === 303) {
      // Presentation is ready, get the presentation details URL
      const presentationUrl = response.headers.get('location');
      return { status: 'completed', presentationUrl };
    } else if (response.status === 200) {
      // Still processing
      return { status: 'processing' };
    } else {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
  } catch (error) {
    console.error('Error checking presentation status:', error);
    throw error;
  }
}

Get Presentation Details

Once the presentation is ready, you can fetch its details:

async function getPresentationDetails(accessToken, presentationUrl) {
  try {
    const response = await fetch(presentationUrl, {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    });

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

    const data = await response.json();

    // Response includes download_url for PDF and other presentation details
    return data;
  } catch (error) {
    console.error('Error getting presentation details:', error);
    throw error;
  }
}

Next Steps

Now that you've learned the basics, you can:

Explore the API Reference for detailed endpoint documentation
Learn about OAuth 2.0 Authorization for more advanced authentication scenarios
Check out our Templates API to manage your presentation templates

For any questions or issues, please contact our support team at support@matik.io.

OAuth 2.0 Authorization Guide

March 1, 2025 · 4 min read

Matik Team

Matik API Team

This guide explains how to implement OAuth 2.0 authentication with the Matik API, including the producer and consumer roles.

Postman users can download this prefilled OAuth collection. Just enter your Client ID and secret.

Understanding Matik's OAuth Roles

Matik's API uses two distinct roles for OAuth authentication:

Producer Role: Used for creating and managing templates, data sources, and other resources
Consumer Role: Used for generating presentations from existing templates without access to data sources.

Prerequisites

Before implementing OAuth 2.0 with Matik, you'll need:

A Matik account with API access
Client credentials (client ID and client secret) with producer and consumer scopes.
Basic understanding of OAuth 2.0 flow

Producer Role Authentication

The producer role has broader permissions and is used for administrative tasks.

Obtaining a Producer Token

Direct user to the following url with a redirect_uri you control.

const authUrl = 'https://app.matik.io/oauth/authorize' + 
  '?response_type=code' +
  '&client_id=YOUR_CLIENT_ID' +
  '&redirect_uri=YOUR_REDIRECT_URI' +
  '&scope=producer+consumer' +
  '&state=OPTIONAL_STATE_VALUE';

Use the code you receive to fetch access and refresh tokens.

async function getToken(code, clientId, clientSecret, redirectUri) {
  try {
    const response = await fetch('https://app.matik.io/api/v1/oauth/token/', {
      method: 'POST',
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: new URLSearchParams({
        grant_type: 'authorization_code',
        client_id: clientId,
        client_secret: clientSecret,
        redirect_uri: redirectUri,
        code: code,
        scope: 'producer consumer'
      })
    });

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

    const data = await response.json();
    return data;
  } catch (error) {
    console.error('Error obtaining producer token:', error);
    throw error;
  }
}

Use the access_token to make a request.

async function createTemplate(name, accessToken) {
  try {
    const response = await fetch('https://app.matik.io/api/1.0/templates/powerpoint', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ name: name })
    });

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

    return await response.json();
  } catch (error) {
    console.error('Error creating template:', error);
    throw error;
  }
}

Consumer Role Authentication

The consumer scope has limited permissions focused on generating presentations.

Using the Consumer Token

async function generatePresentation(templateId, inputs, consumerToken) {
  try {
    const response = await fetch('https://app.matik.io/api/1.0/presentations/', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${consumerToken}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        template_id: templateId,
        inputs: inputs,
        name: "Consumer Generated Presentation"
      })
    });

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

    return await response.json();
  } catch (error) {
    console.error('Error generating presentation:', error);
    throw error;
  }
}

Token Lifecycle Management

OAuth tokens have a limited lifespan. You'll need to refresh the token if it expires.

async function refreshToken(clientId, clientSecret, refreshToken, scope) {
  try {
    const response = await fetch('https://app.matik.io/api/v1/oauth/token/', {
      method: 'POST',
      headers: {
        "Content-Type": "application/x-www-form-urlencoded",
      },
      body: new URLSearchParams({
        grant_type: 'refresh_token',
        client_id: clientId,
        client_secret: clientSecret,
        scope: scope,
        refresh_token: refreshToken
      })
    });

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

    const data = await response.json();
    return data.access_token;
  } catch (error) {
    console.error('Error refreshing token:', error);
    throw error;
  }
}

Best Practices

Store credentials securely: Never expose client secrets in client-side code
Use appropriate roles: Use the producer role only when necessary
Implement token caching: Avoid requesting new tokens for every API call
Handle token expiration: Refresh tokens before they expire
Implement error handling: Handle authentication errors gracefully

Troubleshooting

Common authentication issues and solutions:

Issue	Solution
Invalid client credentials	Double-check your client ID and secret
Token expired	Implement automatic token refresh
Insufficient permissions	Verify you're using the correct role (producer/consumer)
Rate limiting	Implement exponential backoff for retries

Next Steps

Now that you understand OAuth authentication with Matik:

Explore the API Reference for detailed endpoint documentation
Check out our Quick Start Guide for a complete implementation example
Learn about Data Sources to connect your data

For any questions or issues with authentication, please contact our support team at support@matik.io.

Prerequisites​

Getting Started​

Create a Client​

Implement OAuth 2.0​

Generate a Presentation​

Check Presentation Status​

Get Presentation Details​

Next Steps​

Understanding Matik's OAuth Roles​

Prerequisites​

Producer Role Authentication​

Obtaining a Producer Token​

Consumer Role Authentication​

Using the Consumer Token​

Token Lifecycle Management​

Best Practices​

Troubleshooting​

Next Steps​

Prerequisites

Getting Started

Create a Client

Implement OAuth 2.0

Generate a Presentation

Check Presentation Status

Get Presentation Details

Next Steps

Understanding Matik's OAuth Roles

Prerequisites

Producer Role Authentication

Obtaining a Producer Token

Consumer Role Authentication

Using the Consumer Token

Token Lifecycle Management

Best Practices

Troubleshooting

Next Steps